1<?xml version="1.0" standalone="no"?> 2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> 4<!-- 5vim: ts=2 sw=2 sts=2 expandtab: 6--> 7<book> 8 <bookinfo> 9 <title>The NeoMutt E-Mail Client</title> 10 <author> 11 <firstname>Michael</firstname> 12 <surname>Elkins</surname> 13 <email>me@cs.hmc.edu</email> 14 </author> 15 <releaseinfo>version @VERSION@</releaseinfo> 16 <abstract> 17 <para> 18 <quote>All mail clients suck. This one just sucks less.</quote> 19 — me, circa 1995 20 </para> 21 </abstract> 22 </bookinfo> 23 24 <chapter id="intro"> 25 <title>Introduction</title> 26 <para> 27 <emphasis role="bold">NeoMutt</emphasis> is a small but very powerful 28 text-based MIME mail client. NeoMutt is highly configurable, and is well 29 suited to the mail power user with advanced features like key bindings, 30 keyboard macros, mail threading, regular expression searches and 31 a powerful pattern matching language for selecting groups of messages. 32 </para> 33 34 <sect1 id="homepage"> 35 <title>NeoMutt Home Page</title> 36 <para> 37 The homepage can be found at 38 <ulink url="https://neomutt.org">https://neomutt.org</ulink>. 39 </para> 40 </sect1> 41 42 <sect1 id="mailinglists"> 43 <title>Mailing Lists</title> 44 <itemizedlist> 45 <listitem> 46 <para> 47 <email>neomutt-users@neomutt.org</email> – help, bug reports and 48 feature requests. To subscribe to this list, please send a mail to 49 <email>neomutt-users-request@neomutt.org</email> with the subject 50 "subscribe". 51 </para> 52 </listitem> 53 <listitem> 54 <para> 55 <email>neomutt-devel@neomutt.org</email> – development mailing 56 list. To subscribe to this list, please send a mail to 57 <email>neomutt-devel-request@neomutt.org</email> with the subject 58 "subscribe". 59 </para> 60 </listitem> 61 </itemizedlist> 62 </sect1> 63 64 <sect1 id="irc"> 65 <title>NeoMutt Online Resources</title> 66 <variablelist> 67 <varlistentry> 68 <term>Issue Tracking System</term> 69 <listitem> 70 <para> 71 Bugs may be reported on the devel mailing list, or on GitHub: 72 <ulink url="https://github.com/neomutt/neomutt/issues">https://github.com/neomutt/neomutt/issues</ulink> 73 </para> 74 </listitem> 75 </varlistentry> 76 <varlistentry> 77 <term>IRC</term> 78 <listitem> 79 <para> 80 For the IRC user community, visit channel 81 <emphasis>#neomutt</emphasis> on 82 <ulink url="https://kiwiirc.com/nextclient/irc.libera.chat/#neomutt">irc.libera.chat</ulink>. 83 </para> 84 </listitem> 85 </varlistentry> 86 </variablelist> 87 </sect1> 88 89 <sect1 id="contrib"> 90 <title>Contributing to NeoMutt</title> 91 <para> 92 There are various ways to contribute to the NeoMutt project. 93 </para> 94 <para> 95 Especially for new users it may be helpful to meet other new and 96 experienced users to chat about NeoMutt, talk about problems and share 97 tricks. 98 </para> 99 <para> 100 Since translations of NeoMutt into other languages are highly 101 appreciated, the NeoMutt developers always look for skilled translators 102 that help improve and continue to maintain stale translations. 103 </para> 104 <para> 105 For contributing code patches for new features and bug fixes, 106 please refer to the developer pages at 107 <ulink url="https://neomutt.org/dev.html">https://neomutt.org/dev.html</ulink> 108 for more details. 109 </para> 110 </sect1> 111 112 <sect1 id="typo"> 113 <title>Typographical Conventions</title> 114 <para> 115 This section lists typographical conventions followed throughout this 116 manual. See table <xref linkend="tab-typo" /> for typographical 117 conventions for special terms. 118 </para> 119 120 <table id="tab-typo"> 121 <title>Typographical conventions for special terms</title> 122 <tgroup cols="2"> 123 <thead> 124 <row> 125 <entry>Item</entry> 126 <entry>Refers to...</entry> 127 </row> 128 </thead> 129 <tbody> 130 <row> 131 <entry><literal>printf(3)</literal></entry> 132 <entry> 133 UNIX manual pages, execute <literal>man 3 printf</literal> 134 </entry> 135 </row> 136 <row> 137 <entry><literal><PageUp></literal></entry> 138 <entry> 139 named keys 140 </entry> 141 </row> 142 <row> 143 <entry><literal><create-alias></literal></entry> 144 <entry> 145 named NeoMutt function 146 </entry> 147 </row> 148 <row> 149 <entry><literal>^G</literal></entry> 150 <entry> 151 Control+G key combination 152 </entry> 153 </row> 154 <row> 155 <entry>$mail_check</entry> 156 <entry> 157 NeoMutt configuration option 158 </entry> 159 </row> 160 <row> 161 <entry><literal>$HOME</literal></entry> 162 <entry> 163 environment variable 164 </entry> 165 </row> 166 </tbody> 167 </tgroup> 168 </table> 169 <para> 170 Examples are presented as: 171 </para> 172 <screen>neomutt -v</screen> 173 <para> 174 Within command synopsis, curly brackets (<quote>{}</quote>) denote 175 a set of options of which one is mandatory, square brackets 176 (<quote>[]</quote>) denote optional arguments, three dots denote that 177 the argument may be repeated arbitrary times. 178 </para> 179 </sect1> 180 181 <sect1 id="copyright"> 182 <title>Copyright</title> 183 <para> 184 NeoMutt is Copyright © 1996-2021 Michael R. Elkins 185 <email>me@neomutt.org</email> and others. 186 </para> 187 <para> 188 This program is free software; you can redistribute it and/or modify it 189 under the terms of the GNU General Public License as published by the 190 Free Software Foundation; either version 2 of the License, or (at your 191 option) any later version. 192 </para> 193 <para> 194 This program is distributed in the hope that it will be useful, but 195 WITHOUT ANY WARRANTY; without even the implied warranty of 196 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 197 General Public License for more details. 198 </para> 199 <para> 200 You should have received a copy of the GNU General Public License along 201 with this program; if not, write to the Free Software Foundation, Inc., 202 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 203 </para> 204 </sect1> 205 </chapter> 206 207 <chapter id="gettingstarted"> 208 <title>Getting Started</title> 209 <para> 210 This section is intended as a brief overview of how to use NeoMutt. 211 There are many other features which are described elsewhere in the 212 manual. There is even more information available in the NeoMutt FAQ and 213 various web pages. See the 214 <ulink url="https://neomutt.org">NeoMutt homepage</ulink> for more 215 details. 216 </para> 217 <para> 218 The keybindings described in this section are the defaults as 219 distributed. Your local system administrator may have altered the 220 defaults for your site. You can always type <quote>?</quote> in any menu 221 to display the current bindings. 222 </para> 223 <para> 224 The first thing you need to do is invoke NeoMutt, simply by typing 225 <literal>neomutt</literal> at the command line. There are various 226 command-line options, see either the NeoMutt man page or the 227 <link linkend="commandline">reference</link>. 228 </para> 229 230 <sect1 id="core-concepts"> 231 <title>Core Concepts</title> 232 <para> 233 NeoMutt is a text-based application which interacts with users through 234 different menus which are mostly line-/entry-based or page-based. 235 A line-based menu is the so-called <quote>index</quote> menu (listing 236 all messages of the currently opened folder) or the 237 <quote>alias</quote> menu (allowing you to select recipients from 238 a list). Examples for page-based menus are the <quote>pager</quote> 239 (showing one message at a time) or the <quote>help</quote> menu listing 240 all available key bindings. 241 </para> 242 <para> 243 The user interface consists of a context sensitive help line at the 244 top, the menu's contents followed by a context sensitive status line 245 and finally the command line. The command line is used to display 246 informational and error messages as well as for prompts and for 247 entering interactive commands. 248 </para> 249 <para> 250 NeoMutt is configured through variables which, if the user wants to 251 permanently use a non-default value, are written to configuration 252 files. NeoMutt supports a rich config file syntax to make even complex 253 configuration files readable and commentable. 254 </para> 255 <para> 256 Because NeoMutt allows for customizing almost all key bindings, there 257 are so-called <quote>functions</quote> which can be executed manually 258 (using the command line) or in macros. Macros allow the user to bind 259 a sequence of commands to a single key or a short key sequence instead 260 of repeating a sequence of actions over and over. 261 </para> 262 <para> 263 Many commands (such as saving or copying a message to another folder) 264 can be applied to a single message or a set of messages (so-called 265 <quote>tagged</quote> messages). To help selecting messages, NeoMutt 266 provides a rich set of message patterns (such as recipients, sender, 267 body contents, date sent/received, etc.) which can be combined into 268 complex expressions using the boolean <emphasis>and</emphasis> and 269 <emphasis>or</emphasis> operations as well as negating. These patterns 270 can also be used to (for example) search for messages or to limit the 271 index to show only matching messages. 272 </para> 273 <para> 274 NeoMutt supports a <quote>hook</quote> concept which allows the user to 275 execute arbitrary configuration commands and functions in certain 276 situations such as entering a folder, starting a new message or 277 replying to an existing one. These hooks can be used to highly 278 customize NeoMutt's behavior including managing multiple identities, 279 customizing the display for a folder or even implementing 280 auto-archiving based on a per-folder basis and much more. 281 </para> 282 <para> 283 Besides an interactive mode, NeoMutt can also be used as a command-line 284 tool to send messages. See 285 <xref linkend="tab-commandline-options" /> for a complete list of 286 command-line options. 287 </para> 288 </sect1> 289 290 <sect1 id="concept-screens-and-menus"> 291 <title>Screens and Menus</title> 292 293 <sect2 id="intro-index"> 294 <title>Index</title> 295 <para> 296 The index is the screen that you usually see first when you start 297 NeoMutt. It gives an overview over your emails in the currently 298 opened mailbox. By default, this is your system mailbox. The 299 information you see in the index is a list of emails, each with its 300 number on the left, its flags (new email, important email, email that 301 has been forwarded or replied to, tagged email, ...), the date when 302 email was sent, its sender, the email size, and the subject. 303 Additionally, the index also shows thread hierarchies: when you reply 304 to an email, and the other person replies back, you can see the other 305 person's email in a "sub-tree" below. This is especially useful for 306 personal email between a group of people or when you've subscribed to 307 mailing lists. 308 </para> 309 </sect2> 310 311 <sect2 id="intro-pager"> 312 <title>Pager</title> 313 <para> 314 The pager is responsible for showing the email content. On the top of 315 the pager you have an overview over the most important email headers 316 like the sender, the recipient, the subject, and much more 317 information. How much information you actually see depends on your 318 configuration, which we'll describe below. 319 </para> 320 <para> 321 Below the headers, you see the email body which usually contains the 322 message. If the email contains any attachments, you will see more 323 information about them below the email body, or, if the attachments 324 are text files, you can view them directly in the pager. 325 </para> 326 <para> 327 To give the user a good overview, it is possible to configure NeoMutt 328 to show different things in the pager with different colors. 329 Virtually everything that can be described with a regular expression 330 can be colored, e.g. URLs, email addresses or smileys. 331 </para> 332 </sect2> 333 334 <sect2 id="intro-browser"> 335 <title>File Browser</title> 336 <para> 337 The file browser is the interface to the local or remote file system. 338 When selecting a mailbox to open, the browser allows custom sorting 339 of items, limiting the items shown by a regular expression and 340 a freely adjustable format of what to display in which way. It also 341 allows for easy navigation through the file system when selecting 342 file(s) to attach to a message, select multiple files to attach and 343 many more. 344 </para> 345 <para> 346 Some mail systems can nest mail folders inside other mail folders. 347 The normal open entry commands in NeoMutt will open the mail folder and 348 you can't see the sub-folders. If you instead use the 349 <literal><descend-directory></literal> function it will go into 350 the directory and not open it as a mail directory. 351 </para> 352 </sect2> 353 354 <sect2 id="intro-sidebar"> 355 <title>Sidebar</title> 356 <para> 357 The Sidebar shows a list of all your mailboxes. The list can be 358 turned on and off, it can be themed and the list style can be 359 configured. 360 </para> 361 <para> 362 This part of the manual is suitable for beginners. If you already 363 know NeoMutt you could skip ahead to the main 364 <link linkend="sidebar">Sidebar guide</link>. If you just want to get 365 started, you could use the sample 366 <link linkend="sidebar-neomuttrc">Sidebar neomuttrc</link>. 367 </para> 368 <para> 369 To check if NeoMutt supports <quote>Sidebar</quote>, look for the 370 string <literal>+sidebar</literal> in the neomutt version. 371 </para> 372 <screen>neomutt -v</screen> 373 <para> 374 <emphasis role="bold">Let's turn on the Sidebar:</emphasis> 375 </para> 376 377<screen> 378set sidebar_visible 379set sidebar_format = "%B%?F? [%F]?%* %?N?%N/?%S" 380set mail_check_stats 381</screen> 382 383 <para> 384 You will see something like this. A list of mailboxes on the left. 385 A list of emails, from the selected mailbox, on the right. 386 </para> 387 388<screen> 389<emphasis role="indicator">Fruit [1] 3/8</emphasis>| 1 + Jan 24 Rhys Lee (192) Yew 390Animals [1] 2/6| 2 + Feb 11 Grace Hall (167) Ilama 391Cars 4| 3 Feb 23 Aimee Scott (450) Nectarine 392Seas 1/7| 4 ! Feb 28 Summer Jackson (264) Lemon 393 | 5 Mar 07 Callum Harrison (464) Raspberry 394 |<emphasis role="indicator"> 6 N + Mar 24 Samuel Harris (353) Tangerine </emphasis> 395 | 7 N + Sep 05 Sofia Graham (335) Cherry 396 | 8 N Sep 16 Ewan Brown (105) Ugli 397 | 398 | 399</screen> 400 401 <para> 402 This user has four mailboxes: <quote>Fruit</quote>, 403 <quote>Cars</quote>, <quote>Animals</quote> and <quote>Seas</quote>. 404 </para> 405 <para> 406 The current, open, mailbox is <quote>Fruit</quote>. We can also see 407 information about the other mailboxes. For example: The 408 <quote>Animals</quote> mailbox contains, 1 flagged email, 2 new 409 emails out of a total of 6 emails. 410 </para> 411 412 <sect3 id="intro-sidebar-navigation"> 413 <title>Navigation</title> 414 <para> 415 The Sidebar adds some new 416 <link linkend="sidebar-functions">functions</link> to NeoMutt. 417 </para> 418 <para> 419 The user pressed the <quote>c</quote> key to 420 <literal><change-folder></literal> to the 421 <quote>Animals</quote> mailbox. The Sidebar automatically updated 422 the indicator to match. 423 </para> 424 425<screen> 426Fruit [1] 3/8| 1 Jan 03 Tia Gibson (362) Caiman 427<emphasis role="indicator">Animals [1] 2/6</emphasis>| 2 + Jan 22 Rhys Lee ( 48) Dolphin 428Cars 4| 3 ! Aug 16 Ewan Brown (333) Hummingbird 429Seas 1/7| 4 Sep 25 Grace Hall ( 27) Capybara 430 |<emphasis role="indicator"> 5 N + Nov 12 Evelyn Rogers (453) Tapir </emphasis> 431 | 6 N + Nov 16 Callum Harrison (498) Hedgehog 432 | 433 | 434 | 435 | 436</screen> 437 438 <para> 439 Let's map some functions: 440 </para> 441 442<screen> 443bind index,pager \CP sidebar-prev <emphasis role="comment"># Ctrl-P – Previous Mailbox</emphasis> 444bind index,pager \CN sidebar-next <emphasis role="comment"># Ctrl-N – Next Mailbox</emphasis> 445bind index,pager \CO sidebar-open <emphasis role="comment"># Ctrl-O – Open Highlighted Mailbox</emphasis> 446</screen> 447 448 <para> 449 Pressing <quote>Ctrl-N</quote> (Next mailbox) twice will move 450 the Sidebar <emphasis role="bold">highlight</emphasis> to down to 451 the <quote>Seas</quote> mailbox. 452 </para> 453 454<screen> 455Fruit [1] 3/8| 1 Jan 03 Tia Gibson (362) Caiman 456<emphasis role="indicator">Animals [1] 2/6</emphasis>| 2 + Jan 22 Rhys Lee ( 48) Dolphin 457Cars 4| 3 ! Aug 16 Ewan Brown (333) Hummingbird 458<emphasis role="highlight">Seas 1/7</emphasis>| 4 Sep 25 Grace Hall ( 27) Capybara 459 |<emphasis role="indicator"> 5 N + Nov 12 Evelyn Rogers (453) Tapir </emphasis> 460 | 6 N + Nov 16 Callum Harrison (498) Hedgehog 461 | 462 | 463 | 464 | 465</screen> 466 467 <note> 468 <para> 469 Functions <literal><sidebar-next></literal> and 470 <literal><sidebar-prev></literal> move the Sidebar 471 <emphasis role="bold">highlight</emphasis>. They 472 <emphasis role="bold">do not</emphasis> change the open mailbox. 473 </para> 474 </note> 475 <para> 476 Press <quote>Ctrl-O</quote> 477 (<literal><sidebar-open></literal>) to open the highlighted 478 mailbox. 479 </para> 480 481<screen> 482Fruit [1] 3/8| 1 ! Mar 07 Finley Jones (139) Molucca Sea 483Animals [1] 2/6| 2 + Mar 24 Summer Jackson ( 25) Arafura Sea 484Cars 4| 3 + Feb 28 Imogen Baker (193) Pechora Sea 485<emphasis role="indicator">Seas 1/7</emphasis>|<emphasis role="indicator"> 4 N + Feb 23 Isla Hussain (348) Balearic Sea </emphasis> 486 | 487 | 488 | 489 | 490 | 491 | 492</screen> 493 494 </sect3> 495 496 <sect3 id="intro-sidebar-features"> 497 <title>Features</title> 498 <para> 499 The Sidebar shows a list of mailboxes in a panel. 500 </para> 501 <para> 502 Everything about the Sidebar can be configured. 503 </para> 504 <itemizedlist> 505 <title> 506 <link linkend="intro-sidebar-basics">State of the Sidebar</link> 507 </title> 508 <listitem> 509 <para> 510 Visibility 511 </para> 512 </listitem> 513 <listitem> 514 <para> 515 Width 516 </para> 517 </listitem> 518 </itemizedlist> 519 <itemizedlist> 520 <title> 521 <link linkend="intro-sidebar-limit">Which mailboxes are displayed</link> 522 </title> 523 <listitem> 524 <para> 525 Display all 526 </para> 527 </listitem> 528 <listitem> 529 <para> 530 Limit to mailboxes with new mail 531 </para> 532 </listitem> 533 <listitem> 534 <para> 535 Whitelist mailboxes to display always 536 </para> 537 </listitem> 538 </itemizedlist> 539 <itemizedlist> 540 <title> 541 <link linkend="sidebar-sort">The order in which mailboxes are displayed</link> 542 </title> 543 <listitem> 544 <para> 545 Unsorted (order of mailboxes commands) 546 </para> 547 </listitem> 548 <listitem> 549 <para> 550 Sorted alphabetically 551 </para> 552 </listitem> 553 <listitem> 554 <para> 555 Sorted by number of new mails 556 </para> 557 </listitem> 558 </itemizedlist> 559 <itemizedlist> 560 <title> 561 <link linkend="intro-sidebar-colors">Color</link> 562 </title> 563 <listitem> 564 <para> 565 Sidebar indicators and divider 566 </para> 567 </listitem> 568 <listitem> 569 <para> 570 Mailboxes depending on their type 571 </para> 572 </listitem> 573 <listitem> 574 <para> 575 Mailboxes depending on their contents 576 </para> 577 </listitem> 578 </itemizedlist> 579 <itemizedlist> 580 <title> 581 <link linkend="sidebar-functions">Key bindings</link> 582 </title> 583 <listitem> 584 <para> 585 Hide/Unhide the Sidebar 586 </para> 587 </listitem> 588 <listitem> 589 <para> 590 Select previous/next mailbox 591 </para> 592 </listitem> 593 <listitem> 594 <para> 595 Select previous/next mailbox with new mail 596 </para> 597 </listitem> 598 <listitem> 599 <para> 600 Page up/down through a list of mailboxes 601 </para> 602 </listitem> 603 </itemizedlist> 604 <itemizedlist> 605 <title>Misc</title> 606 <listitem> 607 <para> 608 <link linkend="intro-sidebar-format">Formatting string for mailbox</link> 609 </para> 610 </listitem> 611 <listitem> 612 <para> 613 <link linkend="sidebar-next-new-wrap">Wraparound searching</link> 614 </para> 615 </listitem> 616 <listitem> 617 <para> 618 <link linkend="intro-sidebar-abbrev">Flexible mailbox abbreviations</link> 619 </para> 620 </listitem> 621 <listitem> 622 <para> 623 Support for Unicode mailbox names (UTF-8) 624 </para> 625 </listitem> 626 </itemizedlist> 627 </sect3> 628 629 <sect3 id="intro-sidebar-display"> 630 <title>Display</title> 631 <para> 632 Everything about the Sidebar can be configured. 633 </para> 634 <itemizedlist> 635 <title>For a quick reference:</title> 636 <listitem> 637 <para> 638 <link linkend="sidebar-variables">Sidebar variables to set</link> 639 </para> 640 </listitem> 641 <listitem> 642 <para> 643 <link linkend="sidebar-colors">Sidebar colors to apply</link> 644 </para> 645 </listitem> 646 <listitem> 647 <para> 648 <link linkend="sidebar-sort">Sidebar sort methods</link> 649 </para> 650 </listitem> 651 </itemizedlist> 652 653 <sect4 id="intro-sidebar-basics"> 654 <title>Sidebar Basics</title> 655 <para> 656 The most important variable is 657 <literal>$sidebar_visible</literal>. You can set this in your 658 <quote>neomuttrc</quote>, or bind a key to the function 659 <literal><sidebar-toggle-visible></literal>. 660 </para> 661 662<screen> 663set sidebar_visible <emphasis role="comment"># Make the Sidebar visible by default</emphasis> 664bind index,pager B sidebar-toggle-visible <emphasis role="comment"># Use 'B' to switch the Sidebar on and off</emphasis> 665</screen> 666 667 <para> 668 Next, decide how wide you want the Sidebar to be. 25 characters 669 might be enough for the mailbox name and some numbers. Remember, 670 you can hide/show the Sidebar at the press of button. 671 </para> 672 <para> 673 Finally, you might want to change the divider character. By 674 default, Sidebar draws an ASCII line between it and the Index 675 panel. If your terminal supports it, you can use a Unicode 676 line-drawing character. 677 </para> 678 679<screen> 680set sidebar_width = 25 <emphasis role="comment"># Plenty of space</emphasis> 681set sidebar_divider_char = '│' <emphasis role="comment"># Pretty line-drawing character</emphasis> 682</screen> 683 684 </sect4> 685 686 <sect4 id="intro-sidebar-format"> 687 <title>Sidebar Format String</title> 688 <para> 689 <literal>$sidebar_format</literal> allows you to customize the 690 Sidebar display. For an introduction, read 691 <link linkend="index-format">format strings</link> including the 692 section about 693 <link linkend="formatstrings-conditionals">conditionals</link>. 694 </para> 695 <para> 696 The default value is: <literal>%D%* %n</literal> 697 </para> 698 <para> 699 A more detailed value is: 700 <literal>%B%?F? [%F]?%* %?N?%N/?%S</literal> 701 </para> 702 <itemizedlist> 703 <title>Which breaks down as:</title> 704 <listitem> 705 <para> 706 <literal>%B</literal> – Mailbox name 707 </para> 708 </listitem> 709 <listitem> 710 <para> 711 <literal>%?F? [%F]?</literal> – If flagged emails 712 <literal>[%F]</literal>, otherwise nothing 713 </para> 714 </listitem> 715 <listitem> 716 <para> 717 <literal>%*</literal> – Pad with spaces 718 </para> 719 </listitem> 720 <listitem> 721 <para> 722 <literal>%?N?%N/?</literal> – If new emails 723 <literal>%N/</literal>, otherwise nothing 724 </para> 725 </listitem> 726 <listitem> 727 <para> 728 <literal>%S</literal> – Total number of emails 729 </para> 730 </listitem> 731 </itemizedlist> 732 733 <table> 734 <title>sidebar_format</title> 735 <tgroup cols="3"> 736 <thead> 737 <row> 738 <entry>Format</entry> 739 <entry>Notes</entry> 740 <entry>Description</entry> 741 </row> 742 </thead> 743 <tbody> 744 <row> 745 <entry>%B</entry> 746 <entry></entry> 747 <entry> 748 Name of the mailbox 749 </entry> 750 </row> 751 <row> 752 <entry>%d</entry> 753 <entry>* ‡</entry> 754 <entry> 755 Number of deleted messages 756 </entry> 757 </row> 758 <row> 759 <entry>%D</entry> 760 <entry></entry> 761 <entry> 762 Descriptive name of the mailbox 763 </entry> 764 </row> 765 <row> 766 <entry>%F</entry> 767 <entry>* †</entry> 768 <entry> 769 Number of flagged messages in the mailbox 770 </entry> 771 </row> 772 <row> 773 <entry>%L</entry> 774 <entry>* ‡</entry> 775 <entry> 776 Number of messages after limiting 777 </entry> 778 </row> 779 <row> 780 <entry>%n</entry> 781 <entry>*</entry> 782 <entry> 783 If there's new mail, display <quote>N</quote>, otherwise 784 <quote> </quote> (space). 785 </entry> 786 </row> 787 <row> 788 <entry>%N</entry> 789 <entry>* †</entry> 790 <entry> 791 Number of unread messages in the mailbox (seen or unseen) 792 </entry> 793 </row> 794 <row> 795 <entry>%o</entry> 796 <entry>* †</entry> 797 <entry> 798 Number of old messages in the mailbox (unread, but seen) 799 </entry> 800 </row> 801 <row> 802 <entry>%r</entry> 803 <entry>* †</entry> 804 <entry> 805 Number of read messages in the mailbox 806 </entry> 807 </row> 808 <row> 809 <entry>%S</entry> 810 <entry>* †</entry> 811 <entry> 812 Size of mailbox (total number of messages) 813 </entry> 814 </row> 815 <row> 816 <entry>%t</entry> 817 <entry>* ‡</entry> 818 <entry> 819 Number of tagged messages in the mailbox 820 </entry> 821 </row> 822 <row> 823 <entry>%Z</entry> 824 <entry>* †</entry> 825 <entry> 826 Number of new messages in the mailbox (unread, unseen) 827 </entry> 828 </row> 829 <row> 830 <entry>%!</entry> 831 <entry></entry> 832 <entry> 833 <quote>!</quote>: one flagged message; <quote>!!</quote>: 834 two flagged messages; <quote>n!</quote>: n flagged 835 messages (for n > 2). Otherwise prints nothing. 836 </entry> 837 </row> 838 <row> 839 <entry>%>X</entry> 840 <entry></entry> 841 <entry> 842 Right justify the rest of the string and pad with 843 <quote>X</quote> 844 </entry> 845 </row> 846 <row> 847 <entry>%|X</entry> 848 <entry></entry> 849 <entry> 850 Pad to the end of the line with <quote>X</quote> 851 </entry> 852 </row> 853 <row> 854 <entry>%*X</entry> 855 <entry></entry> 856 <entry> 857 Soft-fill with character <quote>X</quote> as pad 858 </entry> 859 </row> 860 </tbody> 861 </tgroup> 862 </table> 863 <para> 864 * = Can be optionally printed if nonzero 865 </para> 866 <para> 867 † = To use these expandos, you must first: 868 </para> 869 <screen>set mail_check_stats</screen> 870 <para> 871 ‡ = Only applicable to the current folder 872 </para> 873 <para> 874 Here are some examples. They show the number of (F)lagged, (N)ew 875 and (S)ize. 876 </para> 877 878 <table> 879 <title>sidebar_format examples</title> 880 <tgroup cols="2"> 881 <thead> 882 <row> 883 <entry>Format</entry> 884 <entry>Example</entry> 885 </row> 886 </thead> 887 <tbody> 888 <row> 889 <entry><literal>%B%?F? [%F]?%* %?N?%N/?%S</literal></entry> 890 <entry><screen>mailbox [F] N/S</screen></entry> 891 </row> 892 <row> 893 <entry><literal>%B%* %F:%N:%S</literal></entry> 894 <entry><screen>mailbox F:N:S</screen></entry> 895 </row> 896 <row> 897 <entry><literal>%B %?N?(%N)?%* %S</literal></entry> 898 <entry><screen>mailbox (N) S</screen></entry> 899 </row> 900 <row> 901 <entry><literal>%B%* ?F?%F/?%N</literal></entry> 902 <entry><screen>mailbox F/S</screen></entry> 903 </row> 904 </tbody> 905 </tgroup> 906 </table> 907 </sect4> 908 909 <sect4 id="intro-sidebar-abbrev"> 910 <title>Abbreviating Mailbox Names</title> 911 <para> 912 <literal>$sidebar_delim_chars</literal> tells Sidebar how to 913 split up mailbox paths. For local directories use 914 <quote>/</quote>; for IMAP folders use <quote>.</quote> 915 </para> 916 917 <sect5 id="intro-sidebar-abbrev-ex1"> 918 <title>Example 1</title> 919 <para> 920 This example works well if your mailboxes have unique names 921 after the last separator. 922 </para> 923 <para> 924 Add some mailboxes of different depths. 925 </para> 926 927<screen> 928set folder="~/mail" 929mailboxes =fruit/apple =fruit/banana =fruit/cherry 930mailboxes =water/sea/sicily =water/sea/archipelago =water/sea/sibuyan 931mailboxes =water/ocean/atlantic =water/ocean/pacific =water/ocean/arctic 932</screen> 933 934 <para> 935 Shorten the names: 936 </para> 937 938<screen> 939set sidebar_short_path <emphasis role="comment"># Shorten mailbox names (truncate all subdirs)</emphasis> 940set sidebar_component_depth=1 <emphasis role="comment"># Shorten mailbox names (truncate 1 subdirs)</emphasis> 941set sidebar_delim_chars="/" <emphasis role="comment"># Delete everything up to the last or Nth / character</emphasis> 942</screen> 943 944 <para> 945 The screenshot below shows what the Sidebar would look like 946 before and after shortening using 947 <literal>sidebar_short_path</literal>. 948 </para> 949 950<screen> 951|fruit/apple |apple 952|fruit/banana |banana 953|fruit/cherry |cherry 954|water/sea/sicily |sicily 955|water/sea/archipelago |archipelago 956|water/sea/sibuyan |sibuyan 957|water/ocean/atlantic |atlantic 958|water/ocean/pacific |pacific 959|water/ocean/arctic |arctic 960</screen> 961 962 <para> 963 The screenshot below shows what the Sidebar would look like 964 before and after shortening using 965 <literal>sidebar_component_depth=1</literal>. 966 </para> 967 968<screen> 969|fruit/apple |apple 970|fruit/banana |banana 971|fruit/cherry |cherry 972|water/sea/sicily |sea/sicily 973|water/sea/archipelago |sea/archipelago 974|water/sea/sibuyan |sea/sibuyan 975|water/ocean/atlantic |ocean/atlantic 976|water/ocean/pacific |ocean/pacific 977|water/ocean/arctic |ocean/arctic 978</screen> 979 980 </sect5> 981 982 <sect5 id="intro-sidebar-abbrev-ex2"> 983 <title>Example 2</title> 984 <para> 985 This example works well if you have lots of mailboxes which are 986 arranged in a tree. 987 </para> 988 <para> 989 Add some mailboxes of different depths. 990 </para> 991 992<screen> 993set folder="~/mail" 994mailboxes =fruit 995mailboxes =fruit/apple =fruit/banana =fruit/cherry 996mailboxes =water 997mailboxes =water/sea 998mailboxes =water/sea/sicily =water/sea/archipelago =water/sea/sibuyan 999mailboxes =water/ocean 1000mailboxes =water/ocean/atlantic =water/ocean/pacific =water/ocean/arctic 1001</screen> 1002 1003 <para> 1004 Shorten the names: 1005 </para> 1006 1007<screen> 1008set sidebar_short_path <emphasis role="comment"># Shorten mailbox names</emphasis> 1009set sidebar_delim_chars="/" <emphasis role="comment"># Delete everything up to the last / character</emphasis> 1010set sidebar_folder_indent <emphasis role="comment"># Indent folders whose names we've shortened</emphasis> 1011set sidebar_indent_string=" " <emphasis role="comment"># Indent with two spaces</emphasis> 1012</screen> 1013 1014 <para> 1015 The screenshot below shows what the Sidebar would look like 1016 before and after shortening. 1017 </para> 1018 1019<screen> 1020|fruit |fruit 1021|fruit/apple | apple 1022|fruit/banana | banana 1023|fruit/cherry | cherry 1024|water |water 1025|water/sea | sea 1026|water/sea/sicily | sicily 1027|water/sea/archipelago | archipelago 1028|water/sea/sibuyan | sibuyan 1029|water/ocean | ocean 1030|water/ocean/atlantic | atlantic 1031|water/ocean/pacific | pacific 1032|water/ocean/arctic | arctic 1033</screen> 1034 1035 <para> 1036 Sometimes, it will be necessary to add mailboxes, that you 1037 don't use, to fill in part of the tree. This will trade 1038 vertical space for horizontal space (but it looks good). 1039 </para> 1040 </sect5> 1041 </sect4> 1042 1043 <sect4 id="intro-sidebar-limit"> 1044 <title>Limiting the Number of Mailboxes</title> 1045 <para> 1046 If you have a lot of mailboxes, sometimes it can be useful to 1047 hide the ones you aren't using. 1048 <literal>$sidebar_new_mail_only</literal> tells Sidebar to only 1049 show mailboxes that contain new, or flagged, email. 1050 </para> 1051 <para> 1052 Sometimes it is useful to only show mailboxes that have mails in 1053 them, while hiding the rest. 1054 <literal>$sidebar_non_empty_mailbox_only</literal> tells the 1055 Sidebar to only show mailboxes with a non-zero number of mails. 1056 </para> 1057 <para> 1058 If you want some mailboxes to be always visible, then use the 1059 <literal>sidebar_whitelist</literal> command. It takes a list of 1060 mailboxes as parameters. 1061 </para> 1062 1063<screen> 1064set sidebar_new_mail_only <emphasis role="comment"># Only mailboxes with new/flagged email</emphasis> 1065sidebar_whitelist +fruit +fruit/apple <emphasis role="comment"># Always display these two mailboxes</emphasis> 1066</screen> 1067 1068 </sect4> 1069 </sect3> 1070 1071 <sect3 id="intro-sidebar-colors"> 1072 <title>Colors</title> 1073 <para> 1074 Here is a sample color scheme: 1075 </para> 1076 1077<screen> 1078color sidebar_indicator default color17 <emphasis role="comment"># Dark blue background</emphasis> 1079color sidebar_highlight white color238 <emphasis role="comment"># Grey background</emphasis> 1080color sidebar_spool_file yellow default <emphasis role="comment"># Yellow</emphasis> 1081color sidebar_unread cyan default <emphasis role="comment"># Light blue</emphasis> 1082color sidebar_new green default <emphasis role="comment"># Green</emphasis> 1083color sidebar_ordinary default default <emphasis role="comment"># Default colors</emphasis> 1084color sidebar_flagged red default <emphasis role="comment"># Red</emphasis> 1085color sidebar_divider color8 default <emphasis role="comment"># Dark grey</emphasis> 1086</screen> 1087 1088 <para> 1089 There is a priority order when coloring Sidebar mailboxes. e.g. If 1090 a mailbox has new mail it will have the 1091 <literal>sidebar_new</literal> color, even if it also contains 1092 flagged mails. 1093 </para> 1094 1095 <table id="table-intro-sidebar-colors"> 1096 <title>Sidebar Color Priority</title> 1097 <tgroup cols="3"> 1098 <thead> 1099 <row> 1100 <entry>Priority</entry> 1101 <entry>Color</entry> 1102 <entry>Description</entry> 1103 </row> 1104 </thead> 1105 <tbody> 1106 <row> 1107 <entry>Highest</entry> 1108 <entry><literal>sidebar_indicator</literal></entry> 1109 <entry>Mailbox is open</entry> 1110 </row> 1111 <row> 1112 <entry></entry> 1113 <entry><literal>sidebar_highlight</literal></entry> 1114 <entry>Mailbox is highlighted</entry> 1115 </row> 1116 <row> 1117 <entry></entry> 1118 <entry><literal>sidebar_new</literal></entry> 1119 <entry>Mailbox contains new mail</entry> 1120 </row> 1121 <row> 1122 <entry></entry> 1123 <entry><literal>sidebar_unread</literal></entry> 1124 <entry>Mailbox contains unread mail</entry> 1125 </row> 1126 <row> 1127 <entry></entry> 1128 <entry><literal>sidebar_flagged</literal></entry> 1129 <entry>Mailbox contains flagged mail</entry> 1130 </row> 1131 <row> 1132 <entry></entry> 1133 <entry><literal>sidebar_spool_file</literal></entry> 1134 <entry>Mailbox is the spool_file (receives incoming mail)</entry> 1135 </row> 1136 <row> 1137 <entry>Lowest</entry> 1138 <entry><literal>sidebar_ordinary</literal></entry> 1139 <entry>Mailbox does not match above</entry> 1140 </row> 1141 </tbody> 1142 </tgroup> 1143 </table> 1144 </sect3> 1145 1146 <sect3 id="intro-sidebar-config-changes"> 1147 <title>Config Changes</title> 1148 <para> 1149 If you haven't used Sidebar before, you can ignore this section. 1150 </para> 1151 <para> 1152 Some of the Sidebar config has been changed to make its meaning 1153 clearer. These changes have been made since the previous Sidebar 1154 release: 2015-11-11. 1155 </para> 1156 1157 <table id="table-intro-sidebar-config-changes"> 1158 <title>Config Changes</title> 1159 <tgroup cols="2"> 1160 <thead> 1161 <row> 1162 <entry>Old Name</entry> 1163 <entry>New Name</entry> 1164 </row> 1165 </thead> 1166 <tbody> 1167 <row> 1168 <entry><literal>$sidebar_delim</literal></entry> 1169 <entry><literal>$sidebar_divider_char</literal></entry> 1170 </row> 1171 <row> 1172 <entry><literal>$sidebar_folderindent</literal></entry> 1173 <entry><literal>$sidebar_folder_indent</literal></entry> 1174 </row> 1175 <row> 1176 <entry><literal>$sidebar_indentstr</literal></entry> 1177 <entry><literal>$sidebar_indent_string</literal></entry> 1178 </row> 1179 <row> 1180 <entry><literal>$sidebar_newmail_only</literal></entry> 1181 <entry><literal>$sidebar_new_mail_only</literal></entry> 1182 </row> 1183 <row> 1184 <entry><literal>$sidebar_shortpath</literal></entry> 1185 <entry><literal>$sidebar_short_path</literal></entry> 1186 </row> 1187 <row> 1188 <entry><literal>$sidebar_sort</literal></entry> 1189 <entry><literal>$sidebar_sort_method</literal></entry> 1190 </row> 1191 <row> 1192 <entry><literal><sidebar-scroll-down></literal></entry> 1193 <entry><literal><sidebar-page-down></literal></entry> 1194 </row> 1195 <row> 1196 <entry><literal><sidebar-scroll-up></literal></entry> 1197 <entry><literal><sidebar-page-up></literal></entry> 1198 </row> 1199 </tbody> 1200 </tgroup> 1201 </table> 1202 </sect3> 1203 </sect2> 1204 1205 <sect2 id="intro-help"> 1206 <title>Help</title> 1207 <para> 1208 The help screen is meant to offer a quick help to the user. It lists 1209 the current configuration of key bindings and their associated 1210 commands including a short description, and currently unbound 1211 functions that still need to be associated with a key binding (or 1212 alternatively, they can be called via the NeoMutt command prompt). 1213 </para> 1214 </sect2> 1215 1216 <sect2 id="intro-compose"> 1217 <title>Compose Menu</title> 1218 <para> 1219 The compose menu features a split screen containing the information 1220 which really matters before actually sending a message by mail: who 1221 gets the message as what (recipients and who gets what kind of copy). 1222 Additionally, users may set security options like deciding whether to 1223 sign, encrypt or sign and encrypt a message with/for what keys. Also, 1224 it's used to attach messages, to re-edit any attachment including the 1225 message itself. 1226 </para> 1227 </sect2> 1228 1229 <sect2 id="intro-alias"> 1230 <title>Alias Menu</title> 1231 <para> 1232 The alias menu is used to help users finding the recipients of 1233 messages. For users who need to contact many people, there's no need 1234 to remember addresses or names completely because it allows for 1235 searching, too. The alias mechanism and thus the alias menu also 1236 features grouping several addresses by a shorter nickname, the actual 1237 alias, so that users don't have to select each single recipient 1238 manually. The alias menu is also used to display the result of 1239 <link linkend="query">external address queries</link>. 1240 </para> 1241 </sect2> 1242 1243 <sect2 id="intro-attach"> 1244 <title>Attachment Menu</title> 1245 <para> 1246 As will be later discussed in detail, NeoMutt features a good and 1247 stable MIME implementation, that is, it supports sending and 1248 receiving messages of arbitrary MIME types. The attachment menu 1249 displays a message's structure in detail: what content parts are 1250 attached to which parent part (which gives a true tree structure), 1251 which part is of what type and what size. Single parts may saved, 1252 deleted or modified to offer great and easy access to message's 1253 internals. 1254 </para> 1255 </sect2> 1256 </sect1> 1257 1258 <sect1 id="menus"> 1259 <title>Moving Around in Menus</title> 1260 <para> 1261 The most important navigation keys common to line- or entry-based menus 1262 are shown in <xref linkend="tab-keys-nav-line" /> and in 1263 <xref linkend="tab-keys-nav-page" /> for page-based menus. 1264 </para> 1265 1266 <table id="tab-keys-nav-line"> 1267 <title>Most common navigation keys in entry-based menus</title> 1268 <tgroup cols="3"> 1269 <thead> 1270 <row> 1271 <entry>Key</entry> 1272 <entry>Function</entry> 1273 <entry>Description</entry> 1274 </row> 1275 </thead> 1276 <tbody> 1277 <row> 1278 <entry>j or <Down></entry> 1279 <entry><literal><next-entry></literal></entry> 1280 <entry>move to the next entry</entry> 1281 </row> 1282 <row> 1283 <entry>k or <Up></entry> 1284 <entry><literal><previous-entry></literal></entry> 1285 <entry>move to the previous entry</entry> 1286 </row> 1287 <row> 1288 <entry>z or <PageDn></entry> 1289 <entry><literal><page-down></literal></entry> 1290 <entry>go to the next page</entry> 1291 </row> 1292 <row> 1293 <entry>Z or <PageUp></entry> 1294 <entry><literal><page-up></literal></entry> 1295 <entry>go to the previous page</entry> 1296 </row> 1297 <row> 1298 <entry>= or <Home></entry> 1299 <entry><literal><first-entry></literal></entry> 1300 <entry>jump to the first entry</entry> 1301 </row> 1302 <row> 1303 <entry>* or <End></entry> 1304 <entry><literal><last-entry></literal></entry> 1305 <entry>jump to the last entry</entry> 1306 </row> 1307 <row> 1308 <entry>q</entry> 1309 <entry><literal><quit></literal></entry> 1310 <entry>exit the current menu</entry> 1311 </row> 1312 <row> 1313 <entry>?</entry> 1314 <entry><literal><help></literal></entry> 1315 <entry>list all keybindings for the current menu</entry> 1316 </row> 1317 </tbody> 1318 </tgroup> 1319 </table> 1320 1321 <table id="tab-keys-nav-page"> 1322 <title>Most common navigation keys in page-based menus</title> 1323 <tgroup cols="3"> 1324 <thead> 1325 <row> 1326 <entry>Key</entry> 1327 <entry>Function</entry> 1328 <entry>Description</entry> 1329 </row> 1330 </thead> 1331 <tbody> 1332 <row> 1333 <entry>J or <Return></entry> 1334 <entry><literal><next-line></literal></entry> 1335 <entry>scroll down one line</entry> 1336 </row> 1337 <row> 1338 <entry><Backspace></entry> 1339 <entry><literal><previous-line></literal></entry> 1340 <entry>scroll up one line</entry> 1341 </row> 1342 <row> 1343 <entry>K, <Space> or <PageDn></entry> 1344 <entry><literal><next-page></literal></entry> 1345 <entry>move to the next page</entry> 1346 </row> 1347 <row> 1348 <entry>- or <PageUp></entry> 1349 <entry><literal><previous-page></literal></entry> 1350 <entry>move the previous page</entry> 1351 </row> 1352 <row> 1353 <entry><Home></entry> 1354 <entry><literal><top></literal></entry> 1355 <entry>move to the top</entry> 1356 </row> 1357 <row> 1358 <entry><End></entry> 1359 <entry><literal><bottom></literal></entry> 1360 <entry>move to the bottom</entry> 1361 </row> 1362 </tbody> 1363 </tgroup> 1364 </table> 1365 </sect1> 1366 1367 <sect1 id="editing"> 1368 <title>Editing Input Fields</title> 1369 1370 <sect2 id="editing-intro"> 1371 <title>Introduction</title> 1372 <para> 1373 NeoMutt has a built-in line editor for inputting text, e.g. email 1374 addresses or filenames. The keys used to manipulate text input are 1375 very similar to those of Emacs. See 1376 <xref linkend="tab-keys-editor" /> for a full reference of available 1377 functions, their default key bindings, and short descriptions. 1378 </para> 1379 1380 <table id="tab-keys-editor"> 1381 <title>Most common line editor keys</title> 1382 <tgroup cols="3"> 1383 <thead> 1384 <row> 1385 <entry>Key</entry> 1386 <entry>Function</entry> 1387 <entry>Description</entry> 1388 </row> 1389 </thead> 1390 <tbody> 1391 <row> 1392 <entry>^A or <Home></entry> 1393 <entry><literal><bol></literal></entry> 1394 <entry>move to the start of the line</entry> 1395 </row> 1396 <row> 1397 <entry>^B or <Left></entry> 1398 <entry><literal><backward-char></literal></entry> 1399 <entry>move back one char</entry> 1400 </row> 1401 <row> 1402 <entry>Esc B</entry> 1403 <entry><literal><backward-word></literal></entry> 1404 <entry>move back one word</entry> 1405 </row> 1406 <row> 1407 <entry>^D or <Delete></entry> 1408 <entry><literal><delete-char></literal></entry> 1409 <entry>delete the char under the cursor</entry> 1410 </row> 1411 <row> 1412 <entry>^E or <End></entry> 1413 <entry><literal><eol></literal></entry> 1414 <entry>move to the end of the line</entry> 1415 </row> 1416 <row> 1417 <entry>^F or <Right></entry> 1418 <entry><literal><forward-char></literal></entry> 1419 <entry>move forward one char</entry> 1420 </row> 1421 <row> 1422 <entry>Esc F</entry> 1423 <entry><literal><forward-word></literal></entry> 1424 <entry>move forward one word</entry> 1425 </row> 1426 <row> 1427 <entry><Tab></entry> 1428 <entry><literal><complete></literal></entry> 1429 <entry>complete filename, alias, or label</entry> 1430 </row> 1431 <row> 1432 <entry>^T</entry> 1433 <entry><literal><complete-query></literal></entry> 1434 <entry>complete address with query</entry> 1435 </row> 1436 <row> 1437 <entry>^K</entry> 1438 <entry><literal><kill-eol></literal></entry> 1439 <entry>delete to the end of the line</entry> 1440 </row> 1441 <row> 1442 <entry>Esc d</entry> 1443 <entry><literal><kill-eow></literal></entry> 1444 <entry>delete to the end of the word</entry> 1445 </row> 1446 <row> 1447 <entry>^W</entry> 1448 <entry><literal><kill-word></literal></entry> 1449 <entry>kill the word in front of the cursor</entry> 1450 </row> 1451 <row> 1452 <entry>^U</entry> 1453 <entry><literal><kill-line></literal></entry> 1454 <entry>delete entire line</entry> 1455 </row> 1456 <row> 1457 <entry>^V</entry> 1458 <entry><literal><quote-char></literal></entry> 1459 <entry>quote the next typed key</entry> 1460 </row> 1461 <row> 1462 <entry><Up></entry> 1463 <entry><literal><history-up></literal></entry> 1464 <entry>recall previous string from history</entry> 1465 </row> 1466 <row> 1467 <entry><Down></entry> 1468 <entry><literal><history-down></literal></entry> 1469 <entry>recall next string from history</entry> 1470 </row> 1471 <row> 1472 <entry>^R</entry> 1473 <entry><literal><history-search></literal></entry> 1474 <entry>use current input to search history</entry> 1475 </row> 1476 <row> 1477 <entry><BackSpace></entry> 1478 <entry><literal><backspace></literal></entry> 1479 <entry>kill the char in front of the cursor</entry> 1480 </row> 1481 <row> 1482 <entry>Esc u</entry> 1483 <entry><literal><upcase-word></literal></entry> 1484 <entry>convert word to upper case</entry> 1485 </row> 1486 <row> 1487 <entry>Esc l</entry> 1488 <entry><literal><downcase-word></literal></entry> 1489 <entry>convert word to lower case</entry> 1490 </row> 1491 <row> 1492 <entry>Esc c</entry> 1493 <entry><literal><capitalize-word></literal></entry> 1494 <entry>capitalize the word</entry> 1495 </row> 1496 <row> 1497 <entry>^G</entry> 1498 <entry>n/a</entry> 1499 <entry>abort</entry> 1500 </row> 1501 <row> 1502 <entry><Return></entry> 1503 <entry>n/a</entry> 1504 <entry>finish editing</entry> 1505 </row> 1506 </tbody> 1507 </tgroup> 1508 </table> 1509 <para> 1510 <literal>^G</literal> is the generic <quote>abort</quote> key 1511 in NeoMutt. In addition to the line editor, it can also be used 1512 to abort prompts. Generally, typing <literal>^G</literal> at a 1513 confirmation prompt or line editor should abort the entire action. 1514 </para> 1515 <para> 1516 You can remap the <emphasis>editor</emphasis> functions using the 1517 <link linkend="bind"><command>bind</command></link> command. For 1518 example, to make the <Delete> key delete the character in front 1519 of the cursor rather than under, you could use: 1520 </para> 1521 <screen>bind editor <delete> backspace</screen> 1522 </sect2> 1523 1524 <sect2 id="editing-history"> 1525 <title>History</title> 1526 <para> 1527 NeoMutt maintains a history for the built-in editor. The number of 1528 items is controlled by the <link linkend="history">$history</link> 1529 variable and can be made persistent using an external file specified 1530 using <link linkend="history-file">$history_file</link> and 1531 <link linkend="save-history">$save_history</link>. You may cycle through 1532 them at an editor prompt by using the 1533 <literal><history-up></literal> and/or 1534 <literal><history-down></literal> commands. NeoMutt will 1535 remember the currently entered text as you cycle through history, and 1536 will wrap around to the initial entry line. 1537 </para> 1538 <para> 1539 NeoMutt maintains several distinct history lists, one for each of the 1540 following categories: 1541 </para> 1542 <itemizedlist> 1543 <listitem> 1544 <para> 1545 <literal>.neomuttrc</literal> commands 1546 </para> 1547 </listitem> 1548 <listitem> 1549 <para> 1550 addresses and aliases 1551 </para> 1552 </listitem> 1553 <listitem> 1554 <para> 1555 shell commands 1556 </para> 1557 </listitem> 1558 <listitem> 1559 <para> 1560 filenames 1561 </para> 1562 </listitem> 1563 <listitem> 1564 <para> 1565 patterns 1566 </para> 1567 </listitem> 1568 <listitem> 1569 <para> 1570 everything else 1571 </para> 1572 </listitem> 1573 </itemizedlist> 1574 <para> 1575 NeoMutt automatically filters out consecutively repeated items from 1576 the history. If 1577 <link linkend="history-remove-dups">$history_remove_dups</link> is 1578 set, all repeated items are removed from the history. It also mimics 1579 the behavior of some shells by ignoring items starting with a space. 1580 The latter feature can be useful in macros to not clobber the 1581 history's valuable entries with unwanted entries. 1582 </para> 1583 </sect2> 1584 </sect1> 1585 1586 <sect1 id="reading"> 1587 <title>Reading Mail</title> 1588 <para> 1589 Similar to many other mail clients, there are two modes in which mail 1590 is read in NeoMutt. The first is a list of messages in the mailbox, 1591 which is called the <quote>index</quote> menu in NeoMutt. The second 1592 mode is the display of the message contents. This is called the 1593 <quote>pager.</quote> 1594 </para> 1595 <para> 1596 The next few sections describe the functions provided in each of these 1597 modes. 1598 </para> 1599 1600 <sect2 id="index-menu"> 1601 <title>The Message Index</title> 1602 <para> 1603 Common keys used to navigate through and manage messages in the index 1604 are shown in <xref linkend="tab-key-index" />. How messages are 1605 presented in the index menu can be customized using the 1606 <link linkend="index-format">$index_format</link> variable. 1607 </para> 1608 1609 <table id="tab-key-index"> 1610 <title>Most common message index keys</title> 1611 <tgroup cols="2"> 1612 <thead> 1613 <row> 1614 <entry>Key</entry> 1615 <entry>Description</entry> 1616 </row> 1617 </thead> 1618 <tbody> 1619 <row> 1620 <entry>c</entry> 1621 <entry>change to a different mailbox</entry> 1622 </row> 1623 <row> 1624 <entry>Esc c</entry> 1625 <entry>change to a folder in read-only mode</entry> 1626 </row> 1627 <row> 1628 <entry>C</entry> 1629 <entry>copy the current message to another mailbox</entry> 1630 </row> 1631 <row> 1632 <entry>Esc C</entry> 1633 <entry>decode a message and copy it to a folder</entry> 1634 </row> 1635 <row> 1636 <entry>Esc s</entry> 1637 <entry>decode a message and save it to a folder</entry> 1638 </row> 1639 <row> 1640 <entry>D</entry> 1641 <entry>delete messages matching a pattern</entry> 1642 </row> 1643 <row> 1644 <entry>d</entry> 1645 <entry>delete the current message</entry> 1646 </row> 1647 <row> 1648 <entry>F</entry> 1649 <entry>mark as important</entry> 1650 </row> 1651 <row> 1652 <entry>l</entry> 1653 <entry>show messages matching a pattern</entry> 1654 </row> 1655 <row> 1656 <entry>N</entry> 1657 <entry>mark message as new</entry> 1658 </row> 1659 <row> 1660 <entry>o</entry> 1661 <entry>change the current sort method</entry> 1662 </row> 1663 <row> 1664 <entry>O</entry> 1665 <entry>reverse sort the mailbox</entry> 1666 </row> 1667 <row> 1668 <entry>q</entry> 1669 <entry>save changes and exit</entry> 1670 </row> 1671 <row> 1672 <entry>s</entry> 1673 <entry>save-message</entry> 1674 </row> 1675 <row> 1676 <entry>T</entry> 1677 <entry>tag messages matching a pattern</entry> 1678 </row> 1679 <row> 1680 <entry>t</entry> 1681 <entry>toggle the tag on a message</entry> 1682 </row> 1683 <row> 1684 <entry>Esc t</entry> 1685 <entry>toggle tag on entire message thread</entry> 1686 </row> 1687 <row> 1688 <entry>U</entry> 1689 <entry>undelete messages matching a pattern</entry> 1690 </row> 1691 <row> 1692 <entry>u</entry> 1693 <entry>undelete-message</entry> 1694 </row> 1695 <row> 1696 <entry>v</entry> 1697 <entry>view-attachments</entry> 1698 </row> 1699 <row> 1700 <entry>x</entry> 1701 <entry>abort changes and exit</entry> 1702 </row> 1703 <row> 1704 <entry><Return></entry> 1705 <entry>display-message</entry> 1706 </row> 1707 <row> 1708 <entry><Tab></entry> 1709 <entry>jump to the next new or unread message</entry> 1710 </row> 1711 <row> 1712 <entry>@</entry> 1713 <entry>show the author's full e-mail address</entry> 1714 </row> 1715 <row> 1716 <entry>$</entry> 1717 <entry>save changes to mailbox</entry> 1718 </row> 1719 <row> 1720 <entry>/</entry> 1721 <entry>search</entry> 1722 </row> 1723 <row> 1724 <entry>Esc /</entry> 1725 <entry>search-reverse</entry> 1726 </row> 1727 <row> 1728 <entry>^L</entry> 1729 <entry>clear and redraw the screen</entry> 1730 </row> 1731 <row> 1732 <entry>^T</entry> 1733 <entry>untag messages matching a pattern</entry> 1734 </row> 1735 </tbody> 1736 </tgroup> 1737 </table> 1738 <para> 1739 In addition to who sent the message and the subject, a short summary 1740 of the disposition of each message is printed beside the message 1741 number. Zero or more of the <quote>flags</quote> in 1742 <xref linkend="tab-msg-status-flags" /> may appear, some of which can 1743 be turned on or off using these functions: 1744 <literal><set-flag></literal> and 1745 <literal><clear-flag></literal> bound by default to 1746 <quote>w</quote> and <quote>W</quote> respectively. 1747 </para> 1748 <para> 1749 Furthermore, the flags in <xref linkend="tab-msg-recip-flags" /> 1750 reflect who the message is addressed to. They can be customized with 1751 the <link linkend="to-chars">$to_chars</link> variable. 1752 </para> 1753 1754 <table id="tab-msg-status-flags"> 1755 <title>Message status flags</title> 1756 <tgroup cols="2"> 1757 <thead> 1758 <row> 1759 <entry>Flag</entry> 1760 <entry>Description</entry> 1761 </row> 1762 </thead> 1763 <tbody> 1764 <row> 1765 <entry>D</entry> 1766 <entry>message is deleted (is marked for deletion)</entry> 1767 </row> 1768 <row> 1769 <entry>d</entry> 1770 <entry>message has attachments marked for deletion</entry> 1771 </row> 1772 <row> 1773 <entry>K</entry> 1774 <entry>contains a PGP public key</entry> 1775 </row> 1776 <row> 1777 <entry>N</entry> 1778 <entry>message is new</entry> 1779 </row> 1780 <row> 1781 <entry>O</entry> 1782 <entry>message is old</entry> 1783 </row> 1784 <row> 1785 <entry>P</entry> 1786 <entry>message is PGP encrypted</entry> 1787 </row> 1788 <row> 1789 <entry>r</entry> 1790 <entry>message has been replied to</entry> 1791 </row> 1792 <row> 1793 <entry>S</entry> 1794 <entry>message is signed, and the signature is successfully 1795 verified</entry> 1796 </row> 1797 <row> 1798 <entry>s</entry> 1799 <entry>message is signed</entry> 1800 </row> 1801 <row> 1802 <entry>!</entry> 1803 <entry>message is flagged</entry> 1804 </row> 1805 <row> 1806 <entry>*</entry> 1807 <entry>message is tagged</entry> 1808 </row> 1809 <row> 1810 <entry>n</entry> 1811 <entry>thread contains new messages (only if collapsed)</entry> 1812 </row> 1813 <row> 1814 <entry>o</entry> 1815 <entry>thread contains old messages (only if collapsed)</entry> 1816 </row> 1817 </tbody> 1818 </tgroup> 1819 </table> 1820 1821 <table id="tab-msg-recip-flags"> 1822 <title>Message recipient flags</title> 1823 <tgroup cols="2"> 1824 <thead> 1825 <row> 1826 <entry>Flag</entry> 1827 <entry>Description</entry> 1828 </row> 1829 </thead> 1830 <tbody> 1831 <row> 1832 <entry>+</entry> 1833 <entry>message is to you and you only</entry> 1834 </row> 1835 <row> 1836 <entry>T</entry> 1837 <entry>message is to you, but also to or CC'ed to 1838 others</entry> 1839 </row> 1840 <row> 1841 <entry>C</entry> 1842 <entry>message is CC'ed to you</entry> 1843 </row> 1844 <row> 1845 <entry>F</entry> 1846 <entry>message is from you</entry> 1847 </row> 1848 <row> 1849 <entry>L</entry> 1850 <entry>message is sent to a subscribed mailing list</entry> 1851 </row> 1852 <row> 1853 <entry>R</entry> 1854 <entry>message has your address in the Reply-To field</entry> 1855 </row> 1856 </tbody> 1857 </tgroup> 1858 </table> 1859 </sect2> 1860 1861 <sect2 id="pager-menu"> 1862 <title>The Pager</title> 1863 <para> 1864 By default, NeoMutt uses its built-in pager to display the contents 1865 of messages (an external pager such as <literal>less(1)</literal> can 1866 be configured, see <link linkend="pager">$pager</link> variable). The 1867 pager is very similar to the Unix program <literal>less(1)</literal> 1868 though not nearly as featureful. 1869 </para> 1870 1871 <table id="tab-key-pager"> 1872 <title>Most common pager keys</title> 1873 <tgroup cols="2"> 1874 <thead> 1875 <row> 1876 <entry>Key</entry> 1877 <entry>Description</entry> 1878 </row> 1879 </thead> 1880 <tbody> 1881 <row> 1882 <entry><Return></entry> 1883 <entry>go down one line</entry> 1884 </row> 1885 <row> 1886 <entry><Space></entry> 1887 <entry>display the next page (or next message if at the end of 1888 a message)</entry> 1889 </row> 1890 <row> 1891 <entry>-</entry> 1892 <entry>go back to the previous page</entry> 1893 </row> 1894 <row> 1895 <entry>n</entry> 1896 <entry>search for next match</entry> 1897 </row> 1898 <row> 1899 <entry>S</entry> 1900 <entry>skip beyond quoted text</entry> 1901 </row> 1902 <row> 1903 <entry>T</entry> 1904 <entry>toggle display of quoted text</entry> 1905 </row> 1906 <row> 1907 <entry>?</entry> 1908 <entry>show keybindings</entry> 1909 </row> 1910 <row> 1911 <entry>/</entry> 1912 <entry>regular expression search</entry> 1913 </row> 1914 <row> 1915 <entry>Esc /</entry> 1916 <entry>backward regular expression search</entry> 1917 </row> 1918 <row> 1919 <entry>\</entry> 1920 <entry>toggle highlighting of search matches</entry> 1921 </row> 1922 <row> 1923 <entry>^</entry> 1924 <entry>jump to the top of the message</entry> 1925 </row> 1926 </tbody> 1927 </tgroup> 1928 </table> 1929 <para> 1930 In addition to key bindings in <xref linkend="tab-key-pager" />, many 1931 of the functions from the index menu are also available in the pager, 1932 such as <literal><delete-message></literal> or 1933 <literal><copy-message></literal> (this is one advantage over 1934 using an external pager to view messages). 1935 </para> 1936 <para> 1937 Also, the internal pager supports a couple other advanced features. 1938 For one, you can set <link linkend="pager-read-delay">$pager_read_delay</link> 1939 to operate in a preview mode, where new messages are not marked 1940 read unless you remain on the message for a certain length of time. 1941 Additionally, it will accept and translate the <quote>standard</quote> 1942 nroff sequences for bold and underline. These sequences are a series 1943 of either the letter, backspace (<quote>^H</quote>), the letter 1944 again for bold or the letter, backspace, <quote>_</quote> for 1945 denoting underline. NeoMutt will attempt to display these in bold and 1946 underline respectively if your terminal supports them. If not, you 1947 can use the bold and underline <link linkend="color">color</link> 1948 objects to specify a <command>color</command> or mono attribute for 1949 them. 1950 </para> 1951 <para> 1952 Additionally, the internal pager supports the ANSI escape sequences 1953 for character attributes. NeoMutt translates them into the correct 1954 color and character settings. The sequences NeoMutt supports are: 1955 </para> 1956 1957<screen> 1958\e[ Ps; Ps; ... Ps;m 1959</screen> 1960 1961 <para> 1962 where <emphasis>Ps</emphasis> can be one of the codes shown in 1963 <xref linkend="tab-ansi-esc" />. 1964 </para> 1965 1966 <table id="tab-ansi-esc"> 1967 <title>ANSI escape sequences</title> 1968 <tgroup cols="2"> 1969 <thead> 1970 <row> 1971 <entry>Escape code</entry> 1972 <entry>Description</entry> 1973 </row> 1974 </thead> 1975 <tbody> 1976 <row> 1977 <entry>0</entry> 1978 <entry> 1979 All attributes off 1980 </entry> 1981 </row> 1982 <row> 1983 <entry>1</entry> 1984 <entry> 1985 Bold on 1986 </entry> 1987 </row> 1988 <row> 1989 <entry>4</entry> 1990 <entry> 1991 Underline on 1992 </entry> 1993 </row> 1994 <row> 1995 <entry>5</entry> 1996 <entry> 1997 Blink on 1998 </entry> 1999 </row> 2000 <row> 2001 <entry>7</entry> 2002 <entry> 2003 Reverse video on 2004 </entry> 2005 </row> 2006 <row> 2007 <entry>3 <emphasis><color></emphasis></entry> 2008 <entry> 2009 Foreground color is <emphasis><color></emphasis> (see 2010 <xref linkend="tab-color" />) 2011 </entry> 2012 </row> 2013 <row> 2014 <entry>4 <emphasis><color></emphasis></entry> 2015 <entry> 2016 Background color is <emphasis><color></emphasis> (see 2017 <xref linkend="tab-color" />) 2018 </entry> 2019 </row> 2020 </tbody> 2021 </tgroup> 2022 </table> 2023 2024 <table id="tab-color"> 2025 <title>Color sequences</title> 2026 <tgroup cols="2"> 2027 <thead> 2028 <row> 2029 <entry>Color code</entry> 2030 <entry>Color</entry> 2031 </row> 2032 </thead> 2033 <tbody> 2034 <row> 2035 <entry>0</entry> 2036 <entry>Black</entry> 2037 </row> 2038 <row> 2039 <entry>1</entry> 2040 <entry>Red</entry> 2041 </row> 2042 <row> 2043 <entry>2</entry> 2044 <entry>Green</entry> 2045 </row> 2046 <row> 2047 <entry>3</entry> 2048 <entry>Yellow</entry> 2049 </row> 2050 <row> 2051 <entry>4</entry> 2052 <entry>Blue</entry> 2053 </row> 2054 <row> 2055 <entry>5</entry> 2056 <entry>Magenta</entry> 2057 </row> 2058 <row> 2059 <entry>6</entry> 2060 <entry>Cyan</entry> 2061 </row> 2062 <row> 2063 <entry>7</entry> 2064 <entry>White</entry> 2065 </row> 2066 </tbody> 2067 </tgroup> 2068 </table> 2069 <para> 2070 NeoMutt uses these attributes for handling 2071 <literal>text/enriched</literal> messages, and they can also be used 2072 by an external <link linkend="auto-view">autoview</link> script for 2073 highlighting purposes. 2074 </para> 2075 <note> 2076 <para> 2077 If you change the colors for your display, for example by changing 2078 the color associated with color2 for your xterm, then that color 2079 will be used instead of green. 2080 </para> 2081 </note> 2082 <note> 2083 <para> 2084 Note that the search commands in the pager take regular 2085 expressions, which are not quite the same as the more complex 2086 <link linkend="patterns">patterns</link> used by the search command 2087 in the index. This is because patterns are used to select messages 2088 by criteria whereas the pager already displays a selected message. 2089 </para> 2090 </note> 2091 </sect2> 2092 2093 <sect2 id="threads"> 2094 <title>Threaded Mode</title> 2095 <para> 2096 So-called <quote>threads</quote> provide a hierarchy of messages 2097 where replies are linked to their parent message(s). This 2098 organizational form is extremely useful in mailing lists where 2099 different parts of the discussion diverge. NeoMutt displays threads 2100 as a tree structure. 2101 </para> 2102 <para> 2103 In NeoMutt, when a mailbox is <link linkend="sort">sorted</link> by 2104 <emphasis>threads</emphasis>, there are a few additional functions 2105 available in the <emphasis>index</emphasis> and 2106 <emphasis>pager</emphasis> modes as shown in 2107 <xref linkend="tab-key-threads" />. 2108 </para> 2109 2110 <table id="tab-key-threads"> 2111 <title>Most common thread mode keys</title> 2112 <tgroup cols="3"> 2113 <thead> 2114 <row> 2115 <entry>Key</entry> 2116 <entry>Function</entry> 2117 <entry>Description</entry> 2118 </row> 2119 </thead> 2120 <tbody> 2121 <row> 2122 <entry>^D</entry> 2123 <entry><literal><delete-thread></literal></entry> 2124 <entry>delete all messages in the current thread</entry> 2125 </row> 2126 <row> 2127 <entry>^U</entry> 2128 <entry><literal><undelete-thread></literal></entry> 2129 <entry>undelete all messages in the current thread</entry> 2130 </row> 2131 <row> 2132 <entry>^N</entry> 2133 <entry><literal><next-thread></literal></entry> 2134 <entry>jump to the start of the next thread</entry> 2135 </row> 2136 <row> 2137 <entry>^P</entry> 2138 <entry><literal><previous-thread></literal></entry> 2139 <entry>jump to the start of the previous thread</entry> 2140 </row> 2141 <row> 2142 <entry>^R</entry> 2143 <entry><literal><read-thread></literal></entry> 2144 <entry>mark the current thread as read</entry> 2145 </row> 2146 <row> 2147 <entry>Esc d</entry> 2148 <entry><literal><delete-subthread></literal></entry> 2149 <entry>delete all messages in the current subthread</entry> 2150 </row> 2151 <row> 2152 <entry>Esc u</entry> 2153 <entry><literal><undelete-subthread></literal></entry> 2154 <entry>undelete all messages in the current subthread</entry> 2155 </row> 2156 <row> 2157 <entry>Esc n</entry> 2158 <entry><literal><next-subthread></literal></entry> 2159 <entry>jump to the start of the next subthread</entry> 2160 </row> 2161 <row> 2162 <entry>Esc p</entry> 2163 <entry><literal><previous-subthread></literal></entry> 2164 <entry>jump to the start of the previous subthread</entry> 2165 </row> 2166 <row> 2167 <entry>Esc r</entry> 2168 <entry><literal><read-subthread></literal></entry> 2169 <entry>mark the current subthread as read</entry> 2170 </row> 2171 <row> 2172 <entry>Esc t</entry> 2173 <entry><literal><tag-thread></literal></entry> 2174 <entry>toggle the tag on the current thread</entry> 2175 </row> 2176 <row> 2177 <entry>Esc v</entry> 2178 <entry><literal><collapse-thread></literal></entry> 2179 <entry>toggle collapse for the current thread</entry> 2180 </row> 2181 <row> 2182 <entry>Esc V</entry> 2183 <entry><literal><collapse-all></literal></entry> 2184 <entry>toggle collapse for all threads</entry> 2185 </row> 2186 <row> 2187 <entry>P</entry> 2188 <entry><literal><parent-message></literal></entry> 2189 <entry>jump to parent message in thread</entry> 2190 </row> 2191 </tbody> 2192 </tgroup> 2193 </table> 2194 2195 <para> 2196 In the <emphasis>index</emphasis>, the subject of threaded children 2197 messages will be prepended with thread tree characters. By default, 2198 the subject itself will not be duplicated unless 2199 <link linkend="hide-thread-subject">$hide_thread_subject</link>is 2200 unset. Special characters will be added to the thread tree as 2201 detailed in <xref linkend="tab-thread-chars" />. 2202 </para> 2203 <table id="tab-thread-chars"> 2204 <title>Special Thread Characters</title> 2205 <tgroup cols="3"> 2206 <thead> 2207 <row> 2208 <entry>Character</entry> 2209 <entry>Description</entry> 2210 <entry>Notes</entry> 2211 </row> 2212 </thead> 2213 <tbody> 2214 <row> 2215 <entry>&</entry> 2216 <entry>hidden message</entry> 2217 <entry>see 2218 <link linkend="hide-limited">$hide_limited</link>and 2219 <link linkend="hide-top-limited">$hide_top_limited</link></entry> 2220 </row> 2221 <row> 2222 <entry>?</entry> 2223 <entry>missing message</entry> 2224 <entry>see 2225 <link linkend="hide-missing">$hide_missing</link>and 2226 <link linkend="hide-top-missing">$hide_top_missing</link></entry> 2227 </row> 2228 <row> 2229 <entry>*</entry> 2230 <entry>pseudo thread</entry> 2231 <entry>see 2232 <link linkend="strict-threads">$strict_threads</link>; not displayed 2233 when <link linkend="narrow-tree">$narrow_tree</link>is set</entry> 2234 </row> 2235 <row> 2236 <entry>=</entry> 2237 <entry>duplicate thread</entry> 2238 <entry>see 2239 <link linkend="duplicate-threads">$duplicate_threads</link>; not 2240 displayed when 2241 <link linkend="narrow-tree">$narrow_tree</link>is set</entry> 2242 </row> 2243 </tbody> 2244 </tgroup> 2245 </table> 2246 2247 <para> 2248 Collapsing a thread displays only the first message in the thread and 2249 hides the others. This is useful when threads contain so many 2250 messages that you can only see a handful of threads on the screen. 2251 See %M in <link linkend="index-format">$index_format</link>. For 2252 example, you could use <quote>%?M?(#%03M)&(%4l)?</quote> in 2253 <link linkend="index-format">$index_format</link> to optionally display 2254 the number of hidden messages if the thread is collapsed. The 2255 <literal>%?<char>?<if-part>&<else-part>?</literal> 2256 syntax is explained in detail in 2257 <link linkend="formatstrings-conditionals">format string conditionals</link>. 2258 </para> 2259 <para> 2260 Technically, every reply should contain a list of its parent messages 2261 in the thread tree, but not all do. In these cases, NeoMutt groups 2262 them by subject which can be controlled using the 2263 <link linkend="strict-threads">$strict_threads</link> variable. 2264 </para> 2265 </sect2> 2266 2267 <sect2 id="reading-misc"> 2268 <title>Miscellaneous Functions</title> 2269 <para> 2270 In addition, the <emphasis>index</emphasis> and 2271 <emphasis>pager</emphasis> menus have these interesting functions: 2272 </para> 2273 <variablelist> 2274 <varlistentry> 2275 <term> 2276 <literal><check-stats></literal> 2277 <anchor id="check-stats" /> 2278 </term> 2279 <listitem> 2280 <para> 2281 Calculate statistics for all monitored mailboxes declared using 2282 the <command>mailboxes</command>command. It will calculate 2283 statistics despite <link linkend="mail-check-stats">$mail_check_stats</link> 2284 being unset. 2285 </para> 2286 </listitem> 2287 </varlistentry> 2288 <varlistentry> 2289 <term> 2290 <literal><create-alias></literal> (default: a) 2291 <anchor id="create-alias" /> 2292 </term> 2293 <listitem> 2294 <para> 2295 Creates a new alias based upon the current message (or prompts 2296 for a new one). Once editing is complete, an 2297 <link linkend="alias"><command>alias</command></link> command 2298 is added to the file specified by the 2299 <link linkend="alias-file">$alias_file</link> variable for 2300 future use 2301 </para> 2302 <note> 2303 <para> 2304 NeoMutt does not read the 2305 <link linkend="alias-file">$alias_file</link> upon startup so 2306 you must explicitly 2307 <link linkend="source"><command>source</command></link> the 2308 file. 2309 </para> 2310 </note> 2311 </listitem> 2312 </varlistentry> 2313 <varlistentry> 2314 <term> 2315 <literal><check-traditional-pgp></literal> (default: Esc P) 2316 <anchor id="check-traditional-pgp" /> 2317 </term> 2318 <listitem> 2319 <para> 2320 This function will search the current message for content 2321 signed or encrypted with PGP the <quote>traditional</quote> 2322 way, that is, without proper MIME tagging. Technically, this 2323 function will temporarily change the MIME content types of the 2324 body parts containing PGP data; this is similar to the 2325 <link linkend="edit-type"><literal><edit-type></literal></link> 2326 function's effect. 2327 </para> 2328 </listitem> 2329 </varlistentry> 2330 <varlistentry> 2331 <term> 2332 <literal><edit-raw-message></literal> 2333 <anchor id="edit-raw-message" /> 2334 </term> 2335 <listitem> 2336 <para> 2337 This command (available in the index and pager) allows you to 2338 edit the raw current message as it's present in the mail 2339 folder. After you have finished editing, the changed message 2340 will be appended to the current folder, and the original 2341 message will be marked for deletion; if the message is 2342 unchanged it won't be replaced. 2343 </para> 2344 <para> 2345 <link linkend="edit"><literal><edit></literal></link> is 2346 a synonym of this for backwards compatibility. 2347 </para> 2348 <para> 2349 See also 2350 <link linkend="edit-or-view-raw-message"><literal><edit-or-view-raw-message></literal></link>, 2351 <link linkend="view-raw-message"><literal><view-raw-message></literal></link>. 2352 </para> 2353 </listitem> 2354 </varlistentry> 2355 <varlistentry> 2356 <term> 2357 <literal><edit></literal> 2358 <anchor id="edit" /> 2359 </term> 2360 <listitem> 2361 <para> 2362 Alias of 2363 <link linkend="edit-raw-message"><literal><edit-raw-message></literal></link> 2364 for backwards compatibility. 2365 </para> 2366 </listitem> 2367 </varlistentry> 2368 <varlistentry> 2369 <term> 2370 <literal><edit-or-view-raw-message></literal> (default: e) 2371 <anchor id="edit-or-view-raw-message" /> 2372 </term> 2373 <listitem> 2374 <para> 2375 This command (available in the index and pager) is the same as 2376 <link linkend="edit-raw-message"><literal><edit-raw-message></literal></link> 2377 if the mailbox is writable, otherwise it the same as 2378 <link linkend="view-raw-message"><literal><view-raw-message></literal></link>. 2379 </para> 2380 </listitem> 2381 </varlistentry> 2382 <varlistentry> 2383 <term> 2384 <literal><edit-type></literal> (default: ^E on the 2385 attachment menu, and in the pager and index menus; ^T on the 2386 compose menu) 2387 <anchor id="edit-type" /> 2388 </term> 2389 <listitem> 2390 <para> 2391 This command is used to temporarily edit an attachment's 2392 content type to fix, for instance, bogus character set 2393 parameters. When invoked from the index or from the pager, 2394 you'll have the opportunity to edit the top-level attachment's 2395 content type. On the 2396 <link linkend="attach-menu">attachment menu</link>, you can 2397 change any attachment's content type. These changes are not 2398 persistent, and get lost upon changing folders. 2399 </para> 2400 <para> 2401 Note that this command is also available on the 2402 <link linkend="compose-menu">compose menu</link>. There, it's 2403 used to fine-tune the properties of attachments you are going 2404 to send. 2405 </para> 2406 </listitem> 2407 </varlistentry> 2408 <varlistentry> 2409 <term> 2410 <literal><enter-command></literal> (default: 2411 <quote>:</quote>) 2412 <anchor id="enter-command" /> 2413 </term> 2414 <listitem> 2415 <para> 2416 This command is used to execute any command you would normally 2417 put in a configuration file. A common use is to check the 2418 settings of variables, or in conjunction with 2419 <link linkend="macro">macros</link> to change settings on the 2420 fly. 2421 </para> 2422 </listitem> 2423 </varlistentry> 2424 <varlistentry> 2425 <term> 2426 <literal><extract-keys></literal> (default: ^K) 2427 <anchor id="extract-keys" /> 2428 </term> 2429 <listitem> 2430 <para> 2431 This command extracts PGP public keys from the current or 2432 tagged message(s) and adds them to your PGP public key ring. 2433 </para> 2434 </listitem> 2435 </varlistentry> 2436 <varlistentry> 2437 <term> 2438 <literal><forget-passphrase></literal> (default: ^F) 2439 <anchor id="forget-passphrase" /> 2440 </term> 2441 <listitem> 2442 <para> 2443 This command wipes the passphrase(s) from memory. It is useful, 2444 if you misspelled the passphrase. 2445 </para> 2446 </listitem> 2447 </varlistentry> 2448 <varlistentry> 2449 <term> 2450 <literal><list-reply></literal> (default: L) 2451 <anchor id="list-reply" /> 2452 </term> 2453 <listitem> 2454 <para> 2455 Reply to the current or tagged message(s) by extracting any 2456 addresses which match the regular expressions given by the 2457 <link linkend="lists"><command>lists</command></link> or 2458 <link linkend="lists"><command>subscribe</command></link> 2459 commands, but also honor any 2460 <literal>Mail-Followup-To</literal> header(s) if the 2461 <link linkend="honor-followup-to">$honor_followup_to</link> 2462 configuration variable is set. In addition, the 2463 <literal>List-Post</literal> header field is examined for 2464 <literal>mailto:</literal> URLs specifying a mailing list 2465 address. Using this when replying to messages posted to 2466 mailing lists helps avoid duplicate copies being sent to the 2467 author of the message you are replying to. 2468 </para> 2469 </listitem> 2470 </varlistentry> 2471 <varlistentry> 2472 <term> 2473 <literal><list-subscribe></literal> 2474 <anchor id="list-subscribe" /> 2475 </term> 2476 <listitem> 2477 <para> 2478 Send an email to the address specified in the List-Subscribe 2479 header as specified in RFC2369. 2480 </para> 2481 </listitem> 2482 </varlistentry> 2483 <varlistentry> 2484 <term> 2485 <literal><list-unsubscribe></literal> 2486 <anchor id="list-unsubscribe" /> 2487 </term> 2488 <listitem> 2489 <para> 2490 Send an email to the address specified in the List-Unsubscribe 2491 header as specified in RFC2369. 2492 </para> 2493 </listitem> 2494 </varlistentry> 2495 <varlistentry> 2496 <term> 2497 <literal><pipe-message></literal> (default: |) 2498 <anchor id="pipe-message" /> 2499 </term> 2500 <listitem> 2501 <para> 2502 Asks for an external Unix command and pipes the current or 2503 tagged message(s) to it. The variables 2504 <link linkend="pipe-decode">$pipe_decode</link>, 2505 <link linkend="pipe-decode-weed">$pipe_decode_weed</link>, 2506 <link linkend="pipe-split">$pipe_split</link>, 2507 <link linkend="pipe-sep">$pipe_sep</link> and 2508 <link linkend="wait-key">$wait_key</link> control the exact 2509 behavior of this function. 2510 </para> 2511 </listitem> 2512 </varlistentry> 2513 <varlistentry> 2514 <term> 2515 <literal><resend-message></literal> (default: Esc e) 2516 <anchor id="resend-message" /> 2517 </term> 2518 <listitem> 2519 <para> 2520 NeoMutt takes the current message as a template for a new 2521 message. This function is best described as "recall from 2522 arbitrary folders". It can conveniently be used to forward MIME 2523 messages while preserving the original mail structure. Note 2524 that the amount of headers included here depends on the value 2525 of the <link linkend="weed">$weed</link> variable. 2526 </para> 2527 <para> 2528 This function is also available from the attachment menu. You 2529 can use this to easily resend a message which was included with 2530 a bounce message as a <literal>message/rfc822</literal> body 2531 part. 2532 </para> 2533 </listitem> 2534 </varlistentry> 2535 <varlistentry> 2536 <term> 2537 <literal><shell-escape></literal> (default: !) 2538 <anchor id="shell-escape" /> 2539 </term> 2540 <listitem> 2541 <para> 2542 Asks for an external Unix command and executes it. The 2543 <link linkend="wait-key">$wait_key</link> can be used to 2544 control whether NeoMutt will wait for a key to be pressed when 2545 the command returns (presumably to let the user read the output 2546 of the command), based on the return status of the named 2547 command. If no command is given, an interactive shell is 2548 executed. 2549 </para> 2550 </listitem> 2551 </varlistentry> 2552 <varlistentry> 2553 <term> 2554 <literal><skip-headers></literal> (default: H) 2555 <anchor id="skip-headers"/> 2556 </term> 2557 <listitem> 2558 <para> 2559 This function will skip to the first line of the body, 2560 past the headers of the current message, regardless of 2561 current position. 2562 </para> 2563 </listitem> 2564 </varlistentry> 2565 <varlistentry> 2566 <term> 2567 <literal><view-raw-message></literal> 2568 <anchor id="view-raw-message" /> 2569 </term> 2570 <listitem> 2571 <para> 2572 This command (available in the index and pager) opens the raw 2573 message read-only in an editor. This command does not allow 2574 editing the message, use 2575 <link linkend="edit-raw-message"><literal><edit-raw-message></literal></link> 2576 for this. 2577 </para> 2578 <para> 2579 See also 2580 <link linkend="edit-raw-message"><literal><edit-raw-message></literal></link>, 2581 <link linkend="edit-or-view-raw-message"><literal><edit-or-view-raw-message></literal></link>. 2582 </para> 2583 </listitem> 2584 </varlistentry> 2585 <varlistentry> 2586 <term> 2587 <literal><skip-quoted></literal> (default: S) 2588 <anchor id="skip-quoted" /> 2589 </term> 2590 <listitem> 2591 <para> 2592 This function will make the internal pager go forward 2593 to the next segment of non-quoted body text (whether 2594 the first line of the body after headers, or following 2595 a line of quoted text), or print a message if no 2596 further unquoted text can be found. 2597 </para> 2598 <para> 2599 The variable 2600 <link linkend="pager-skip-quoted-context">$pager_skip_quoted_context</link> 2601 can be used to show some quoted context prior to the 2602 selected line. 2603 </para> 2604 </listitem> 2605 </varlistentry> 2606 <varlistentry> 2607 <term> 2608 <literal><toggle-quoted></literal><anchor id="toggle-quoted"/> 2609 (default: T) 2610 </term> 2611 <listitem> 2612 <para> 2613 The pager uses the <link linkend="quote-regex">$quote_regex</link> 2614 variable to detect quoted text when displaying the body of the message. 2615 This function toggles the display of the quoted material in the message. 2616 It is particularly useful when being interested in just the response and 2617 there is a large amount of quoted text in the way. 2618 </para> 2619 <para> 2620 The variable 2621 <link linkend="toggle-quoted-show-levels">$toggle_quoted_show_levels</link> 2622 can be used to show some context by continuing to show that number of levels 2623 rather than hiding all quoted levels. 2624 </para> 2625 </listitem> 2626 </varlistentry> 2627 </variablelist> 2628 </sect2> 2629 </sect1> 2630 2631 <sect1 id="sending"> 2632 <title>Sending Mail</title> 2633 2634 <sect2 id="sending-intro"> 2635 <title>Introduction</title> 2636 <para> 2637 The bindings shown in 2638 <xref linkend="tab-key-send" /> are available in the 2639 <emphasis>index</emphasis> and <emphasis>pager</emphasis> to start 2640 a new message. 2641 </para> 2642 2643 <table id="tab-key-send"> 2644 <title>Most common mail sending keys</title> 2645 <tgroup cols="3"> 2646 <thead> 2647 <row> 2648 <entry>Key</entry> 2649 <entry>Function</entry> 2650 <entry>Description</entry> 2651 </row> 2652 </thead> 2653 <tbody> 2654 <row> 2655 <entry>m</entry> 2656 <entry><literal><mail></literal></entry> 2657 <entry>compose a new message</entry> 2658 </row> 2659 <row> 2660 <entry>r</entry> 2661 <entry><literal><reply></literal></entry> 2662 <entry>reply to sender</entry> 2663 </row> 2664 <row> 2665 <entry>g</entry> 2666 <entry><literal><group-reply></literal></entry> 2667 <entry>reply to all recipients</entry> 2668 </row> 2669 <row> 2670 <entry></entry> 2671 <entry><literal><group-chat-reply></literal></entry> 2672 <entry>reply to all recipients preserving To/Cc</entry> 2673 </row> 2674 <row> 2675 <entry>L</entry> 2676 <entry><literal><list-reply></literal></entry> 2677 <entry>reply to a mailing list</entry> 2678 </row> 2679 <row> 2680 <entry>L</entry> 2681 <entry><literal><list-subscribe></literal></entry> 2682 <entry>send a subscription email to a mailing list</entry> 2683 </row> 2684 <row> 2685 <entry>L</entry> 2686 <entry><literal><list-unsubscribe></literal></entry> 2687 <entry>send an unsubscription email to a mailing list</entry> 2688 </row> 2689 <row> 2690 <entry>f</entry> 2691 <entry><literal><forward></literal></entry> 2692 <entry>forward message</entry> 2693 </row> 2694 <row> 2695 <entry>b</entry> 2696 <entry><literal><bounce></literal></entry> 2697 <entry>bounce (remail) message</entry> 2698 </row> 2699 <row> 2700 <entry>Esc k</entry> 2701 <entry><literal><mail-key></literal></entry> 2702 <entry>mail a PGP public key to someone</entry> 2703 </row> 2704 </tbody> 2705 </tgroup> 2706 </table> 2707 <para> 2708 <emphasis>Bouncing</emphasis> a message sends the message as-is to 2709 the recipient you specify. <emphasis>Forwarding</emphasis> a message 2710 allows you to add comments or modify the message you are forwarding. 2711 These items are discussed in greater detail in the next section 2712 <quote><link linkend="forwarding-mail">Forwarding and Bouncing Mail</link></quote>. 2713 </para> 2714 <para> 2715 NeoMutt will then enter the <emphasis>compose</emphasis> menu and 2716 prompt you for the recipients to place on the <quote>To:</quote> 2717 header field when you hit <literal>m</literal> to start a new 2718 message. Next, it will ask you for the <quote>Subject:</quote> field 2719 for the message, providing a default if you are replying to or 2720 forwarding a message. You again have the chance to adjust recipients, 2721 subject, and security settings right before actually sending the 2722 message. See also 2723 <link linkend="ask-cc">$ask_cc</link>, 2724 <link linkend="ask-bcc">$ask_bcc</link>, 2725 <link linkend="auto-edit">$auto_edit</link>, 2726 <link linkend="bounce">$bounce</link>, 2727 <link linkend="fast-reply">$fast_reply</link>, and 2728 <link linkend="include">$include</link> for changing how and if 2729 NeoMutt asks these questions. 2730 </para> 2731 <para> 2732 When replying, NeoMutt fills these fields with proper values 2733 depending on the reply type. The types of replying supported are: 2734 </para> 2735 <variablelist> 2736 <varlistentry> 2737 <term>Simple reply</term> 2738 <listitem> 2739 <para> 2740 Reply to the author directly. 2741 </para> 2742 </listitem> 2743 </varlistentry> 2744 <varlistentry> 2745 <term>Group reply</term> 2746 <listitem> 2747 <para> 2748 Reply to the author; cc all other recipients; consults 2749 <link linkend="alternates"><command>alternates</command></link> 2750 and excludes you. 2751 </para> 2752 </listitem> 2753 </varlistentry> 2754 <varlistentry> 2755 <term>Group Chat reply</term> 2756 <listitem> 2757 <para> 2758 Reply to the author and other recipients in the To list; 2759 cc other recipients in the Cc list; consults 2760 <link linkend="alternates"><command>alternates</command></link> 2761 and excludes you. 2762 </para> 2763 </listitem> 2764 </varlistentry> 2765 <varlistentry> 2766 <term>List reply</term> 2767 <listitem> 2768 <para> 2769 Reply to all mailing list addresses found, either specified via 2770 configuration or auto-detected. See <xref linkend="lists" /> 2771 for details. 2772 </para> 2773 </listitem> 2774 </varlistentry> 2775 </variablelist> 2776 <para> 2777 After getting recipients for new messages, forwards or replies, 2778 NeoMutt will then automatically start your 2779 <link linkend="editor">$editor</link> on the message body. If the 2780 <link linkend="edit-headers">$edit_headers</link> variable is set, 2781 the headers will be at the top of the message in your editor; the 2782 message body should start on a new line after the existing blank line 2783 at the end of headers. Any messages you are replying to will be added 2784 in sort order to the message, with appropriate 2785 <link linkend="attribution">$attribution</link>, 2786 <link linkend="indent-string">$indent_string</link> and 2787 <link linkend="post-indent-string">$post_indent_string</link>. When 2788 forwarding a message, if the 2789 <link linkend="mime-forward">$mime_forward</link> variable is unset, 2790 a copy of the forwarded message will be included. If you have 2791 specified a <link linkend="signature">$signature</link>, it will be 2792 appended to the message. 2793 </para> 2794 <para> 2795 Once you have finished editing the body of your mail message, you are 2796 returned to the <emphasis>compose</emphasis> menu providing the 2797 functions shown in <xref linkend="tab-func-compose" /> to modify, 2798 send or postpone the message. 2799 </para> 2800 2801 <table id="tab-func-compose"> 2802 <title>Most common compose menu keys</title> 2803 <tgroup cols="3"> 2804 <thead> 2805 <row> 2806 <entry>Key</entry> 2807 <entry>Function</entry> 2808 <entry>Description</entry> 2809 </row> 2810 </thead> 2811 <tbody> 2812 <row> 2813 <entry>a</entry> 2814 <entry><literal><attach-file></literal></entry> 2815 <entry>attach a file</entry> 2816 </row> 2817 <row> 2818 <entry>A</entry> 2819 <entry><literal><attach-message></literal></entry> 2820 <entry>attach message(s) to the message</entry> 2821 </row> 2822 <row> 2823 <entry>Esc k</entry> 2824 <entry><literal><attach-key></literal></entry> 2825 <entry>attach a PGP public key</entry> 2826 </row> 2827 <row> 2828 <entry>d</entry> 2829 <entry><literal><edit-description></literal></entry> 2830 <entry>edit description on attachment</entry> 2831 </row> 2832 <row> 2833 <entry>D</entry> 2834 <entry><literal><detach-file></literal></entry> 2835 <entry>detach a file</entry> 2836 </row> 2837 <row> 2838 <entry>t</entry> 2839 <entry><literal><edit-to></literal></entry> 2840 <entry>edit the To field</entry> 2841 </row> 2842 <row> 2843 <entry>Esc f</entry> 2844 <entry><literal><edit-from></literal></entry> 2845 <entry>edit the From field</entry> 2846 </row> 2847 <row> 2848 <entry>r</entry> 2849 <entry><literal><edit-reply-to></literal></entry> 2850 <entry>edit the Reply-To field</entry> 2851 </row> 2852 <row> 2853 <entry>c</entry> 2854 <entry><literal><edit-cc></literal></entry> 2855 <entry>edit the Cc field</entry> 2856 </row> 2857 <row> 2858 <entry>b</entry> 2859 <entry><literal><edit-bcc></literal></entry> 2860 <entry>edit the Bcc field</entry> 2861 </row> 2862 <row> 2863 <entry>y</entry> 2864 <entry><literal><send-message></literal></entry> 2865 <entry>send the message</entry> 2866 </row> 2867 <row> 2868 <entry>s</entry> 2869 <entry><literal><edit-subject></literal></entry> 2870 <entry>edit the Subject</entry> 2871 </row> 2872 <row> 2873 <entry>S</entry> 2874 <entry><literal><smime-menu></literal></entry> 2875 <entry>select S/MIME options</entry> 2876 </row> 2877 <row> 2878 <entry>f</entry> 2879 <entry><literal><edit-fcc></literal></entry> 2880 <entry>specify an 2881 <quote>Fcc</quote> mailbox</entry> 2882 </row> 2883 <row> 2884 <entry>p</entry> 2885 <entry><literal><pgp-menu></literal></entry> 2886 <entry>select PGP options</entry> 2887 </row> 2888 <row> 2889 <entry>P</entry> 2890 <entry><literal><postpone-message></literal></entry> 2891 <entry>postpone this message until later</entry> 2892 </row> 2893 <row> 2894 <entry>q</entry> 2895 <entry><literal><quit></literal></entry> 2896 <entry>quit (abort) sending the message</entry> 2897 </row> 2898 <row> 2899 <entry>w</entry> 2900 <entry><literal><write-fcc></literal></entry> 2901 <entry>write the message to a folder</entry> 2902 </row> 2903 <row> 2904 <entry>i</entry> 2905 <entry><literal><ispell></literal></entry> 2906 <entry>check spelling (if available on your system)</entry> 2907 </row> 2908 <row> 2909 <entry>^F</entry> 2910 <entry><literal><forget-passphrase></literal></entry> 2911 <entry>wipe passphrase(s) from memory</entry> 2912 </row> 2913 </tbody> 2914 </tgroup> 2915 </table> 2916 <para> 2917 The compose menu is also used to edit the attachments for a message 2918 which can be either files or other messages. The 2919 <literal><attach-message></literal> function to will prompt you 2920 for a folder to attach messages from. You can now tag messages in 2921 that folder and they will be attached to the message you are sending. 2922 </para> 2923 <note> 2924 <para> 2925 Note that certain operations like composing a new mail, replying, 2926 forwarding, etc. are not permitted when you are in that folder. The 2927 %r in <link linkend="status-format">$status_format</link> will 2928 change to a <quote>A</quote> to indicate that you are in 2929 attach-message mode. 2930 </para> 2931 </note> 2932 <para> 2933 After exiting the compose menu via <literal><send-message></literal>, 2934 the message will be sent. If configured and enabled, this can happen via 2935 <link linkend="sending-mixmaster">mixmaster</link> or 2936 <link linkend="smtp">$smtp_url</link>. Otherwise 2937 <link linkend="sendmail">$sendmail</link> will be invoked. Prior to 2938 version 2019-11-29, NeoMutt enabled <link linkend="write-bcc">$write_bcc</link> by 2939 default, assuming the MTA would automatically remove a 2940 <literal>Bcc:</literal> header as part of delivery. Starting with 2019-11-29, the 2941 option is unset by default, but no longer affects the fcc copy of the message. 2942 </para> 2943 </sect2> 2944 2945 <sect2 id="edit-header"> 2946 <title>Editing the Message Header</title> 2947 <para> 2948 When editing the header because of 2949 <link linkend="edit-headers">$edit_headers</link> being set, there are 2950 a several pseudo headers available which will not be included in sent 2951 messages but trigger special NeoMutt behavior. 2952 </para> 2953 2954 <sect3 id="fcc-header"> 2955 <title>Fcc: Pseudo Header</title> 2956 <para> 2957 If you specify 2958 </para> 2959 <para> 2960 <literal>Fcc:</literal> <emphasis>filename</emphasis> 2961 </para> 2962 <para> 2963 as a header, NeoMutt will pick up <emphasis>filename</emphasis> 2964 just as if you had used the <literal><edit-fcc></literal> 2965 function in the <emphasis>compose</emphasis> menu. It can later be 2966 changed from the compose menu. 2967 </para> 2968 </sect3> 2969 2970 <sect3 id="attach-header"> 2971 <title>Attach: Pseudo Header</title> 2972 <para> 2973 You can also attach files to your message by specifying 2974 </para> 2975 <para> 2976 <literal>Attach:</literal> 2977 <emphasis>filename</emphasis> [<emphasis>description</emphasis>] 2978 </para> 2979 <para> 2980 where <emphasis>filename</emphasis> is the file to attach and 2981 <emphasis>description</emphasis> is an optional string to use as 2982 the description of the attached file. Spaces in filenames have to 2983 be escaped using backslash (<quote>\</quote>). The file can be 2984 removed as well as more added from the compose menu. 2985 </para> 2986 </sect3> 2987 2988 <sect3 id="pgp-header"> 2989 <title>Pgp: Pseudo Header</title> 2990 <para> 2991 If you want to use PGP, you can specify 2992 </para> 2993 <para> 2994 <literal>Pgp:</literal> [ 2995 <literal>E</literal> | 2996 <literal>S</literal> | 2997 <literal>S</literal> 2998 <emphasis><id></emphasis> ] 2999 </para> 3000 <para> 3001 <quote>E</quote> selects encryption, <quote>S</quote> selects signing 3002 and <quote>S<id></quote> selects signing with the given key, 3003 setting <link linkend="pgp-sign-as">$pgp_sign_as</link> for the 3004 duration of the message composition session. The selection can later 3005 be changed in the compose menu. 3006 </para> 3007 </sect3> 3008 3009 <sect3 id="in-reply-to-header"> 3010 <title>In-Reply-To: Header</title> 3011 <para> 3012 When replying to messages, the <emphasis>In-Reply-To:</emphasis> 3013 header contains the Message-Id of the message(s) you reply to. If 3014 you remove or modify its value, NeoMutt will not generate 3015 a <emphasis>References:</emphasis> field, which allows you to 3016 create a new message thread, for example to create a new message to 3017 a mailing list without having to enter the mailing list's address. 3018 </para> 3019 <para> 3020 If you intend to start a new thread by replying, please make really 3021 sure you remove the <emphasis>In-Reply-To:</emphasis> header in 3022 your editor. Otherwise, though you'll produce a technically valid 3023 reply, some netiquette guardians will be annoyed by this so-called 3024 <quote>thread hijacking</quote>. 3025 </para> 3026 </sect3> 3027 </sect2> 3028 3029 <sect2 id="sending-crypto"> 3030 <title>Sending Cryptographically Signed/Encrypted Messages</title> 3031 <para> 3032 If you have told NeoMutt to PGP or S/MIME encrypt a message, it will 3033 guide you through a key selection process when you try to send the 3034 message. NeoMutt will not ask you any questions about keys which have 3035 a certified user ID matching one of the message recipients' mail 3036 addresses. However, there may be situations in which there are 3037 several keys, weakly certified user ID fields, or where no matching 3038 keys can be found. 3039 </para> 3040 <para> 3041 In these cases, you are dropped into a menu with a list of keys from 3042 which you can select one. When you quit this menu, or NeoMutt can't 3043 find any matching keys, you are prompted for a user ID. You can, as 3044 usually, abort this prompt using <literal>^G</literal>. When you do 3045 so, NeoMutt will return to the compose screen. 3046 </para> 3047 <para> 3048 Once you have successfully finished the key selection, the message 3049 will be encrypted using the selected public keys when sent out. 3050 </para> 3051 <para> 3052 To ensure you can view encrypted messages you have sent, you may wish 3053 to set <link linkend="pgp-self-encrypt">$pgp_self_encrypt</link> and 3054 <link linkend="pgp-default-key">$pgp_default_key</link> for PGP, or 3055 <link linkend="smime-self-encrypt">$smime_self_encrypt</link> and 3056 <link linkend="smime-default-key">$smime_default_key</link> for 3057 S/MIME. 3058 </para> 3059 <para> 3060 Most fields of the entries in the key selection menu (see also 3061 <link linkend="pgp-entry-format">$pgp_entry_format</link>) have 3062 obvious meanings. But some explanations on the capabilities, flags, 3063 and validity fields are in order. 3064 </para> 3065 <para> 3066 The flags sequence (<quote>%f</quote>) will expand to one of the 3067 flags in <xref linkend="tab-pgp-menuflags" />. 3068 </para> 3069 3070 <table id="tab-pgp-menuflags"> 3071 <title>PGP key menu flags</title> 3072 <tgroup cols="2"> 3073 <thead> 3074 <row> 3075 <entry>Flag</entry> 3076 <entry>Description</entry> 3077 </row> 3078 </thead> 3079 <tbody> 3080 <row> 3081 <entry>R</entry> 3082 <entry>The key has been revoked and can't be used.</entry> 3083 </row> 3084 <row> 3085 <entry>X</entry> 3086 <entry>The key is expired and can't be used.</entry> 3087 </row> 3088 <row> 3089 <entry>d</entry> 3090 <entry>You have marked the key as disabled.</entry> 3091 </row> 3092 <row> 3093 <entry>c</entry> 3094 <entry>There are unknown critical self-signature packets.</entry> 3095 </row> 3096 </tbody> 3097 </tgroup> 3098 </table> 3099 <para> 3100 The capabilities field (<quote>%c</quote>) expands to 3101 a two-character sequence representing a key's capabilities. The first 3102 character gives the key's encryption capabilities: A minus sign 3103 (<quote>-</quote>) means that the key cannot be used for encryption. 3104 A dot (<quote>.</quote>) means that it's marked as a signature key 3105 in one of the user IDs, but may also be used for encryption. The 3106 letter <quote>e</quote> indicates that this key can be used for 3107 encryption. 3108 </para> 3109 <para> 3110 The second character indicates the key's signing capabilities. Once 3111 again, a <quote>-</quote> implies <quote>not for signing</quote>, 3112 <quote>.</quote> implies that the key is marked as an encryption key 3113 in one of the user-ids, and <quote>s</quote> denotes a key which can 3114 be used for signing. 3115 </para> 3116 <para> 3117 Finally, the validity field (<quote>%t</quote>) indicates how 3118 well-certified a user-id is. A question mark (<quote>?</quote>) 3119 indicates undefined validity, a minus character (<quote>-</quote>) 3120 marks an untrusted association, a space character means a partially 3121 trusted association, and a plus character (<quote>+</quote>) 3122 indicates complete validity. 3123 </para> 3124 </sect2> 3125 3126 <sect2 id="ff"> 3127 <title>Sending Format=Flowed Messages</title> 3128 3129 <sect3 id="ff-concept"> 3130 <title>Concept</title> 3131 <para> 3132 <literal>format=flowed</literal>-style messages (or 3133 <literal>f=f</literal> for short) are <literal>text/plain</literal> 3134 messages that consist of paragraphs which a receiver's mail client 3135 may reformat to its own needs which mostly means to customize line 3136 lengths regardless of what the sender sent. Technically this is 3137 achieved by letting lines of a <quote>flowable</quote> paragraph 3138 end in spaces except for the last line. 3139 </para> 3140 <para> 3141 While for text-mode clients like NeoMutt it's the best way to 3142 assume only a standard 80x25 character cell terminal, it may be 3143 desired to let the receiver decide completely how to view 3144 a message. 3145 </para> 3146 </sect3> 3147 3148 <sect3 id="ff-support"> 3149 <title>NeoMutt Support</title> 3150 <para> 3151 NeoMutt only supports setting the required 3152 <literal>format=flowed</literal> MIME parameter on outgoing 3153 messages if the <link linkend="text-flowed">$text_flowed</link> 3154 variable is set, specifically it does not add the trailing spaces. 3155 </para> 3156 <para> 3157 After editing, NeoMutt properly space-stuffs the message. 3158 <emphasis>Space-stuffing</emphasis> is required by RFC3676 defining 3159 <literal>format=flowed</literal> and means to prepend a space to: 3160 </para> 3161 <itemizedlist> 3162 <listitem> 3163 <para> 3164 all lines starting with a space 3165 </para> 3166 </listitem> 3167 <listitem> 3168 <para> 3169 lines starting with the word 3170 <quote><literal>From</literal></quote> followed by space 3171 </para> 3172 </listitem> 3173 <listitem> 3174 <para> 3175 all lines starting with 3176 <quote><literal>></literal></quote> which is not intended to 3177 be a quote character 3178 </para> 3179 </listitem> 3180 </itemizedlist> 3181 <note> 3182 <para> 3183 NeoMutt only supports space-stuffing for the first two types of 3184 lines but not for the third: It is impossible to safely detect 3185 whether a leading <literal>></literal> character starts a quote 3186 or not. 3187 </para> 3188 </note> 3189 <para> 3190 All leading spaces are to be removed by receiving clients to 3191 restore the original message prior to further processing. 3192 </para> 3193 </sect3> 3194 3195 <sect3 id="ff-editor"> 3196 <title>Editor Considerations</title> 3197 <para> 3198 As NeoMutt provides no additional features to compose 3199 <literal>f=f</literal> messages, it's completely up to the user and 3200 his editor to produce proper messages. Please consider your 3201 editor's documentation if you intend to send <literal>f=f</literal> 3202 messages. 3203 </para> 3204 <para> 3205 For example, <emphasis>vim</emphasis> provides the 3206 <literal>w</literal> flag for its <literal>formatoptions</literal> 3207 setting to assist in creating <literal>f=f</literal> messages, see 3208 <literal>:help fo-table</literal> for details. 3209 </para> 3210 </sect3> 3211 3212 <sect3 id="ff-pager"> 3213 <title>Reformatting</title> 3214 <para> 3215 NeoMutt has some support for reformatting when viewing and replying 3216 to <literal>format=flowed</literal> messages. In order to take 3217 advantage of these, <link linkend="reflow-text">$reflow_text</link> 3218 must be set. 3219 </para> 3220 <itemizedlist> 3221 <listitem> 3222 <para> 3223 Paragraphs are automatically reflowed and wrapped at a width 3224 specified by <link linkend="reflow-wrap">$reflow_wrap</link>. 3225 </para> 3226 </listitem> 3227 <listitem> 3228 <para> 3229 In its original format, the quoting style of 3230 <literal>format=flowed</literal> messages can be difficult to 3231 read, and doesn't intermix well with non-flowed replies. 3232 Setting 3233 <link linkend="reflow-space-quotes">$reflow_space_quotes</link> 3234 adds spaces after each level of quoting when in the pager and 3235 replying in a non-flowed format (i.e. with 3236 <link linkend="text-flowed">$text_flowed</link> unset). 3237 </para> 3238 </listitem> 3239 <listitem> 3240 <para> 3241 If 3242 <link linkend="reflow-space-quotes">$reflow_space_quotes</link> 3243 is unset, NeoMutt will still add one trailing space after all 3244 the quotes in the pager (but not when replying). 3245 </para> 3246 </listitem> 3247 </itemizedlist> 3248 </sect3> 3249 </sect2> 3250 </sect1> 3251 3252 <sect1 id="forwarding-mail"> 3253 <title>Forwarding and Bouncing Mail</title> 3254 <para> 3255 Bouncing and forwarding let you send an existing message to recipients 3256 that you specify. Bouncing a message sends a verbatim copy of a message 3257 to alternative addresses as if they were the message's original 3258 recipients specified in the Bcc header. Forwarding a message, on the 3259 other hand, allows you to modify the message before it is resent (for 3260 example, by adding your own comments). Bouncing is done using the 3261 <literal><bounce></literal> function and forwarding using the 3262 <literal><forward></literal> function bound to <quote>b</quote> 3263 and <quote>f</quote> respectively. 3264 </para> 3265 <para> 3266 Forwarding can be done by including the original message in the new 3267 message's body (surrounded by indicating lines) or including it as 3268 a MIME attachment, depending on the value of the 3269 <link linkend="mime-forward">$mime_forward</link> variable. Decoding of 3270 attachments, like in the pager, can be controlled by the 3271 <link linkend="forward-decode">$forward_decode</link> and 3272 <link linkend="mime-forward-decode">$mime_forward_decode</link> 3273 variables, respectively. The desired forwarding format may depend on 3274 the content, therefore 3275 <link linkend="mime-forward">$mime_forward</link> is a quadoption 3276 which, for example, can be set to <quote>ask-no</quote>. 3277 </para> 3278 <para> 3279 NeoMutt's default (<link linkend="mime-forward">$mime_forward</link>=<quote>no</quote> and 3280 <link linkend="forward-decode">$forward_decode</link>=<quote>yes</quote>) is 3281 to use standard inline forwarding. In that mode all text-decodable 3282 parts are included in the new message body. Other attachments from 3283 the original email can also be attached to the new message, based on the 3284 quadoption <link linkend="forward-attachments">$forward_attachments</link>. 3285 </para> 3286 <para> 3287 The inclusion of headers is controlled by the current setting of the 3288 <link linkend="weed">$weed</link> variable, unless 3289 <link linkend="mime-forward">$mime_forward</link> is set. 3290 </para> 3291 <para> 3292 By default a forwarded message does not reference the messages it 3293 contains. When 3294 <link linkend="forward-references">$forward_references</link> is set, 3295 a forwarded message includes the <quote>In-Reply-To:</quote> and 3296 <quote>References:</quote> headers, just like a reply would. Hence the 3297 forwarded message becomes part of the original thread instead of 3298 starting a new one. 3299 </para> 3300 <para> 3301 Editing the message to forward follows the same procedure as sending or 3302 replying to a message does, but can be disabled via the quadoption 3303 <link linkend="forward-edit">$forward_edit</link>. 3304 </para> 3305 </sect1> 3306 3307 <sect1 id="postponing-mail"> 3308 <title>Postponing Mail</title> 3309 <para> 3310 At times it is desirable to delay sending a message that you have 3311 already begun to compose. When the 3312 <literal><postpone-message></literal> function is used in the 3313 <emphasis>compose</emphasis> menu, the body of your message and 3314 attachments are stored in the mailbox specified by the 3315 <link linkend="postponed">$postponed</link> variable. This means that 3316 you can recall the message even if you exit NeoMutt and then restart it 3317 at a later time. 3318 </para> 3319 <para> 3320 Once a message is postponed, there are several ways to resume it. From 3321 the command line you can use the <quote>-p</quote> option, or if you 3322 compose a new message from the <emphasis>index</emphasis> or 3323 <emphasis>pager</emphasis> you will be prompted if postponed messages 3324 exist. If multiple messages are currently postponed, the 3325 <emphasis>postponed</emphasis> menu will pop up and you can select 3326 which message you would like to resume. 3327 </para> 3328 <note> 3329 <para> 3330 If you postpone a reply to a message, the reply setting of the 3331 message is only updated when you actually finish the message and send 3332 it. Also, you must be in the same folder with the message you replied 3333 to for the status of the message to be updated. 3334 </para> 3335 </note> 3336 <para> 3337 See also the <link linkend="postpone">$postpone</link> quad-option. 3338 </para> 3339 </sect1> 3340 3341 <sect1 id="logging"> 3342 <title>Logging</title> 3343 <para> 3344 NeoMutt has different types of logging/error messages 3345 </para> 3346 <itemizedlist> 3347 <listitem> 3348 <para> 3349 Primitive Errors: errors emitted by C library functions such as 3350 <literal>fopen()</literal>. 3351 </para> 3352 </listitem> 3353 <listitem> 3354 <para> 3355 Errors 3356 </para> 3357 </listitem> 3358 <listitem> 3359 <para> 3360 Warnings 3361 </para> 3362 </listitem> 3363 <listitem> 3364 <para> 3365 Message: Informational messages such as 3366 <literal>Sorting mailbox...</literal>. 3367 </para> 3368 </listitem> 3369 <listitem> 3370 <para> 3371 Debug: Debug messages usually only interesting while debugging. 3372 </para> 3373 </listitem> 3374 </itemizedlist> 3375 <para> 3376 These log messages are shown in the command bar at the bottom of the UI 3377 (usually below the status line) and errors are shown in a different 3378 colour than the other message types. The colours used for displaying 3379 can be adjusted with <literal>color error ...</literal> and 3380 <literal>color message ...</literal>, respectively. See the 3381 <link linkend="color">description of <literal>color</literal></link> 3382 for the precise syntax. 3383 </para> 3384 <para> 3385 The command bar shows only the last message. To show the last 100 3386 messages (this includes all types of messages from debug to error) the 3387 function 3388 <link linkend="tab-index-bindings"><literal><show-log-messages></literal></link> 3389 can be used. 3390 </para> 3391 <para> 3392 Debug messages are not shown by default. To enable them NeoMutt must be 3393 compiled with <literal>+debug</literal>. Furthermore, the debug log 3394 level must be set with the 3395 <link linkend="tab-commandline-options"><literal>-d</literal> command line parameter</link> 3396 at startup. The <literal>-d</literal> parameter expects a debug level 3397 which can range from 1 to 5 and affects verbosity of the debug 3398 messages. A value of 2 is recommended for the start. If debug logging 3399 is enabled, all log messages (i.e. errors, warnings, ..., debug) are 3400 additionally written to the file <literal>~/.neomuttdebug0</literal>. 3401 </para> 3402 </sect1> 3403 3404 <sect1 id="encryption"> 3405 <title>Encryption and Signing</title> 3406 3407 <para> 3408 NeoMutt supports encrypting and signing emails when used interactively. 3409 In batch mode, cryptographic operations are disabled, so these options 3410 can't be used to sign an email sent via a cron job, for instance. 3411 </para> 3412 3413 <para> 3414 OpenPGP and S/MIME are enabled in one of two ways: <quote>classic 3415 mode</quote> or GPGME. The former invokes external programs to perform 3416 the various operations; it is better tested and more flexible, but 3417 requires some configuration. The latter uses the GnuPG project's GPGME 3418 library. 3419 </para> 3420 3421 <para> 3422 To enable <quote>classic mode</quote>, ensure GPGME is disabled and use 3423 the <literal>gpg.rc</literal> or <literal>smime.rc</literal> files that 3424 come with NeoMutt. These are typically installed under 3425 <literal>/usr/local/share/doc/neomutt/samples/</literal>. Source them, either 3426 directly or by copying them to your .mutt directory and sourcing them. 3427 Sourcing them directly from 3428 <literal>/usr/local/share/doc/neomutt/samples/</literal> has the benefit of 3429 automatically using fixes and security improvements to the command 3430 invocations, and is recommended. 3431 </para> 3432 3433<screen> 3434unset crypt_use_gpgme 3435source /usr/local/share/doc/neomutt/samples/gpg.rc 3436source /usr/local/share/doc/neomutt/samples/smime.rc 3437</screen> 3438 3439 <para> 3440 To use GPGME instead, simply ensure the option is enabled in your .muttrc: 3441 </para> 3442 3443<screen> 3444set crypt_use_gpgme 3445</screen> 3446 3447 <sect2 id="enc-pgp"> 3448 <title>OpenPGP Configuration</title> 3449 3450 <para> 3451 The two most important settings are 3452 <link linkend="pgp-default-key">$pgp_default_key</link> and 3453 <link linkend="pgp-sign-as">$pgp_sign_as</link>. To perform 3454 encryption, you must set the first variable. If you have a separate 3455 signing key, or only have a signing key, then set the second. Most 3456 people will only need to set 3457 <link linkend="pgp-default-key">$pgp_default_key</link>. 3458 </para> 3459 3460 <para> 3461 Starting with version 2.1.0, GnuPG automatically uses an 3462 <literal>agent</literal> to prompt for your passphrase. If you are 3463 using a version older than that, you'll need to ensure an agent is 3464 running (alternatively, you can unset 3465 <link linkend="pgp-use-gpg-agent">$pgp_use_gpg_agent</link> and NeoMutt 3466 will prompt you for your passphrase). The agent in turn uses a 3467 <literal>pinentry</literal> program to display the prompt. There are 3468 many different kinds of pinentry programs that can be used: qt, gtk2, 3469 gnome3, fltk, and curses. However, NeoMutt does 3470 <emphasis>not</emphasis> work properly with the tty pinentry program. 3471 Please ensure you have one of the GUI or curses pinentry programs 3472 installed and configured to be the default for your system. 3473 </para> 3474 </sect2> 3475 3476 <sect2 id="enc-smime"> 3477 <title>S/MIME Configuration</title> 3478 3479 <para> 3480 As with OpenPGP, the two most important settings are 3481 <link linkend="smime-default-key">$smime_default_key</link> and 3482 <link linkend="smime-sign-as">$smime_sign_as</link>. To perform 3483 encryption and decryption, you must set the first variable. If you 3484 have a separate signing key, or only have a signing key, then set the 3485 second. Most people will only need to set 3486 <link linkend="smime-default-key">$smime_default_key</link>. 3487 </para> 3488 3489 <para> 3490 In <quote>classic mode</quote>, keys and certificates are managed by 3491 the <literal>smime_keys</literal> program that comes with NeoMutt. By 3492 default they are stored under <literal>~/.smime/</literal>. (This is 3493 set by the <literal>smime.rc</literal> file with 3494 <link linkend="smime-certificates">$smime_certificates</link> and 3495 <link linkend="smime-keys">$smime_keys</link>.) To initialize this 3496 directory, use the command <quote><literal>smime_keys 3497 init</literal></quote> from a shell prompt. The program can be then 3498 be used to import and list certificates. You may also want to 3499 periodically run <quote><literal>smime_keys refresh</literal></quote> 3500 to update status flags for your certificates. 3501 </para> 3502 </sect2> 3503 </sect1> 3504 3505 </chapter> 3506 3507 <chapter id="configuration"> 3508 <title>Configuration</title> 3509 3510 <sect1 id="configuration-files"> 3511 <title>Location of Initialization Files</title> 3512 <para> 3513 When NeoMutt starts up it looks for two configuration files – one 3514 <quote>system</quote> file and one <quote>user</quote> file. 3515 </para> 3516 <para> 3517 NeoMutt first reads the system configuration file, then the user 3518 configuration file. The two files are merged in the sense that "last 3519 setting wins". That is, if a setting is defined in both files, the user 3520 configuration file's value for that setting is the one that takes 3521 precedence and becomes effective. 3522 </para> 3523 <para> 3524 NeoMutt searches for several different file names when looking for 3525 config. It looks for NeoMutt config files before Mutt config files and 3526 versioned config before plain config. For example: 3527 </para> 3528 3529 <table id="neomuttrc-order"> 3530 <title>NeoMutt config file search order</title> 3531 <tgroup cols="1"> 3532 <tbody> 3533 <row> 3534 <entry>neomuttrc</entry> 3535 </row> 3536 <row> 3537 <entry>muttrc</entry> 3538 </row> 3539 </tbody> 3540 </tgroup> 3541 </table> 3542 <para> 3543 This allows the user to create separate NeoMutt and Mutt config files 3544 on the same system. 3545 </para> 3546 3547 <sect2 id="neomuttrc-system"> 3548 <title>Location of system config files</title> 3549 <para> 3550 NeoMutt will search for a system config file in 3551 a <literal>neomutt</literal> directory in several places. First it 3552 searches the locations specified in the 3553 <literal>XDG_CONFIG_DIRS</literal> environment variable, which 3554 defaults to <literal>/etc/xdg</literal>. Next, it looks in 3555 <literal>/etc</literal>. Finally, it tries 3556 <literal>/usr/share</literal>. 3557 </para> 3558 <para> 3559 The system config file will not be read if the <quote>-n</quote> 3560 option is used on the 3561 <link linkend="commandline">command line</link>. 3562 </para> 3563 <para> 3564 NeoMutt will read just one file, the first file it finds, from the 3565 list below. 3566 </para> 3567 3568 <table id="neomuttrc-system-files"> 3569 <title>NeoMutt system config file locations</title> 3570 <tgroup cols="2"> 3571 <thead> 3572 <row> 3573 <entry>File Location</entry> 3574 <entry>Notes</entry> 3575 </row> 3576 </thead> 3577 <tbody> 3578 <row> 3579 <entry>/etc/xdg/neomutt/neomuttrc</entry> 3580 <entry></entry> 3581 </row> 3582 <row> 3583 <entry>/etc/xdg/neomutt/Muttrc</entry> 3584 <entry>Note the case of the filename</entry> 3585 </row> 3586 <row> 3587 <entry>/etc/neomuttrc</entry> 3588 <entry></entry> 3589 </row> 3590 <row> 3591 <entry>/etc/Muttrc</entry> 3592 <entry>Note the case of the filename</entry> 3593 </row> 3594 <row> 3595 <entry>/usr/share/neomutt/neomuttrc</entry> 3596 <entry></entry> 3597 </row> 3598 <row> 3599 <entry>/usr/share/neomutt/Muttrc</entry> 3600 <entry>Note the case of the filename</entry> 3601 </row> 3602 </tbody> 3603 </tgroup> 3604 </table> 3605 </sect2> 3606 3607 <sect2 id="neomuttrc-user"> 3608 <title>Location of user config files</title> 3609 <para> 3610 NeoMutt will search for a user config file in several places. First 3611 it looks in the directory specified in the 3612 <literal>XDG_CONFIG_HOME</literal> environment variable, which 3613 defaults to <literal>~/.config/neomutt</literal>. Next, it looks in 3614 <literal>~</literal> (your home directory). Finally, it tries 3615 <literal>~/.neomutt</literal>. 3616 </para> 3617 <para> 3618 You may specify your own location for the user config file using the 3619 <quote>-F</quote> option on the 3620 <link linkend="commandline">command line</link>. 3621 </para> 3622 <para> 3623 NeoMutt will read just one file, the first file it finds, from the 3624 list below. 3625 </para> 3626 3627 <table id="neomuttrc-user-files"> 3628 <title>NeoMutt user config file locations</title> 3629 <tgroup cols="1"> 3630 <thead> 3631 <row> 3632 <entry>File Location</entry> 3633 </row> 3634 </thead> 3635 <tbody> 3636 <row> 3637 <entry>~/.config/neomutt/neomuttrc</entry> 3638 </row> 3639 <row> 3640 <entry>~/.config/neomutt/muttrc</entry> 3641 </row> 3642 <row> 3643 <entry>~/.config/mutt/neomuttrc</entry> 3644 </row> 3645 <row> 3646 <entry>~/.config/mutt/muttrc</entry> 3647 </row> 3648 <row> 3649 <entry>~/.neomutt/neomuttrc</entry> 3650 </row> 3651 <row> 3652 <entry>~/.neomutt/muttrc</entry> 3653 </row> 3654 <row> 3655 <entry>~/.mutt/neomuttrc</entry> 3656 </row> 3657 <row> 3658 <entry>~/.mutt/muttrc</entry> 3659 </row> 3660 <row> 3661 <entry>~/.neomuttrc</entry> 3662 </row> 3663 <row> 3664 <entry>~/.muttrc</entry> 3665 </row> 3666 </tbody> 3667 </tgroup> 3668 </table> 3669 </sect2> 3670 3671 <sect2 id="config-priority"> 3672 <title>Config Priority</title> 3673 <para> 3674 The majority of NeoMutt's config will be read from two files: the 3675 system config in <literal>/etc</literal> and the user config in, e.g. 3676 <literal>~/.neomuttrc</literal> 3677 </para> 3678 <para> 3679 The last file that gets read will overwrite any settings from 3680 previous config files. This means that an administrator can set some 3681 defaults which the user can override. 3682 </para> 3683 <para> 3684 Additionally, there are a handful of config items which can be set 3685 using an environment variable. They have a lower priority than the 3686 NeoMutt config files: 3687 <link linkend="editor">$editor</link>, 3688 <link linkend="from">$from</link>, 3689 <link linkend="mailcap-path">$mailcap_path</link>, 3690 <link linkend="news-server">$news_server</link>, 3691 <link linkend="shell">shell</link>, 3692 <link linkend="spool-file">$spool_file</link>, 3693 <link linkend="tmpdir">$tmpdir</link>, 3694 </para> 3695 <para> 3696 Finally, it's possible to 3697 <link linkend="commandline">set some variables directly</link> on the 3698 command-line using the <literal>-e</literal> option. 3699 </para> 3700 3701 <table id="table-config-priority"> 3702 <title>Config Priority</title> 3703 <tgroup cols="3"> 3704 <thead> 3705 <row> 3706 <entry>Priority</entry> 3707 <entry>Where</entry> 3708 <entry>Example</entry> 3709 </row> 3710 </thead> 3711 <tbody> 3712 <row> 3713 <entry>Highest</entry> 3714 <entry>Command line</entry> 3715 <entry><literal>neomutt -e 'set from="John Doe <john@example.com>"'</literal></entry> 3716 </row> 3717 <row> 3718 <entry></entry> 3719 <entry>User Config</entry> 3720 <entry><literal>~/.neomuttrc</literal></entry> 3721 </row> 3722 <row> 3723 <entry></entry> 3724 <entry>System Config</entry> 3725 <entry><literal>/etc/neomuttrc</literal></entry> 3726 </row> 3727 <row> 3728 <entry></entry> 3729 <entry>Environment</entry> 3730 <entry><literal>export EDITOR="/usr/bin/vim"</literal></entry> 3731 </row> 3732 <row> 3733 <entry>Lowest</entry> 3734 <entry>Built-in</entry> 3735 <entry>Defaults hard-coded into NeoMutt</entry> 3736 </row> 3737 </tbody> 3738 </tgroup> 3739 </table> 3740 </sect2> 3741 </sect1> 3742 3743 <sect1 id="quickconfig"> 3744 <title>Starter NeoMuttrc</title> 3745 3746 <para> 3747 NeoMutt is highly configurable because it's <emphasis>meant</emphasis> 3748 to be customized to your needs and preferences. However, this 3749 configurability can make it difficult when just getting started. A few 3750 sample neomuttrc files come with NeoMutt, under 3751 <literal>doc/neomutt/samples/</literal>. Among them, 3752 <ulink url="https://github.com/neomutt/neomutt/blob/master/contrib/samples/sample.neomuttrc-starter">sample.neomuttrc-starter</ulink> 3753 is a basic example config with a few suggested settings and pointers to 3754 useful programs. 3755 </para> 3756 </sect1> 3757 3758 <sect1 id="neomuttrc-syntax" xreflabel="Syntax of Initialization Files"> 3759 <title>Syntax of Initialization Files</title> 3760 <para> 3761 An initialization file consists of a series of 3762 <link linkend="commands">commands</link>. Each line of the file may 3763 contain one or more commands. When multiple commands are used, they 3764 must be separated by a semicolon (<quote>;</quote>). 3765 </para> 3766 <example id="ex-rc-multiple-cmds"> 3767 <title>Multiple configuration commands per line</title> 3768 <screen>set real_name='John Smith' ; ignore x-</screen> 3769 </example> 3770 <para> 3771 The hash mark, or pound sign (<quote>#</quote>), is used as 3772 a <quote>comment</quote> character. You can use it to annotate your 3773 initialization file. All text after the comment character to the end of 3774 the line is ignored. 3775 </para> 3776 <example id="ex-ec-comment"> 3777 <title>Commenting configuration files</title> 3778 3779<screen> 3780my_hdr X-Disclaimer: Why are you listening to me? <emphasis role="comment"># This is a comment</emphasis> 3781</screen> 3782 3783 </example> 3784 <para> 3785 Single quotes (<quote>'</quote>) and double quotes (<quote>"</quote>) 3786 can be used to quote strings which contain spaces or other special 3787 characters. The difference between the two types of quotes is similar 3788 to that of many popular shell programs, namely that a single quote is 3789 used to specify a literal string (one that is not interpreted for shell 3790 variables or quoting with a backslash [see next paragraph]), while 3791 double quotes indicate a string for which should be evaluated. For 3792 example, backticks are evaluated inside of double quotes, but 3793 <emphasis>not</emphasis> for single quotes. 3794 </para> 3795 <para> 3796 <quote>\</quote> quotes the next character, just as in shells such as 3797 bash and zsh. For example, if want to put quotes <quote>"</quote> 3798 inside of a string, you can use <quote>\</quote> to force the next 3799 character to be a literal instead of interpreted character. 3800 </para> 3801 <example id="ex-rc-quote"> 3802 <title>Escaping quotes in configuration files</title> 3803 <screen>set real_name="Michael \"MuttDude\" Elkins"</screen> 3804 </example> 3805 <para> 3806 <quote>\\</quote> means to insert a literal <quote>\</quote> into the 3807 line. <quote>\n</quote> and <quote>\r</quote> have their usual 3808 C meanings of linefeed and carriage-return, respectively. 3809 </para> 3810 <para> 3811 A <quote>\</quote> at the end of a line can be used to split commands 3812 over multiple lines as it <quote>escapes</quote> the line end, provided 3813 that the split points don't appear in the middle of command names. 3814 Lines are first concatenated before interpretation so that a multi-line 3815 can be commented by commenting out the first line only. 3816 </para> 3817 <example id="ex-rc-split"> 3818 <title>Splitting long configuration commands over several lines</title> 3819 3820<screen> 3821set status_format="some very \ 3822long value split \ 3823over several lines" 3824</screen> 3825 3826 </example> 3827 <note> 3828 <para> 3829 Using <quote>\</quote> at the end of a line <emphasis>only</emphasis> 3830 removes the newline character. 3831 </para> 3832 <para> 3833 Any leading whitespace on the following lines will be part of the configuration. 3834 </para> 3835 </note> 3836 <para> 3837 It is also possible to substitute the output of a Unix command in an 3838 initialization file. This is accomplished by enclosing the command in 3839 backticks (``). In <xref linkend="ex-rc-backtick" />, the output of the 3840 Unix command <quote>uname -a</quote> will be substituted before the 3841 line is parsed. Since initialization files are line oriented, only the 3842 first line of output from the Unix command will be substituted. 3843 </para> 3844 <example id="ex-rc-backtick"> 3845 <title>Using external command's output in configuration files</title> 3846 <screen>my_hdr X-Operating-System: `uname -a`</screen> 3847 </example> 3848 <para> 3849 To avoid the output of backticks being parsed, place them inside double 3850 quotes. In <xref linkend="ex-backtick-dblquotes"/>, the output of the 3851 gpg decryption is assigned directly to $imap_pass, so that special 3852 characters in the password (e.g.<quote>'</quote>, <quote>#</quote>, 3853 <quote>$</quote>) are not parsed and interpreted specially by neomutt. 3854 </para> 3855 <example id="ex-backtick-dblquotes"> 3856 <title>Preventing the output of backticks from being parsed</title> 3857<screen> 3858set imap_pass="`gpg --batch -q --decrypt ~/.neomutt/account.gpg`" 3859</screen> 3860 </example> 3861 <para> 3862 Both environment variables and NeoMutt variables can be accessed by 3863 prepending <quote>$</quote> to the name of the variable. For example, 3864 </para> 3865 <example id="ex-rc-env"> 3866 <title>Using environment variables in configuration files</title> 3867 <screen>set record=+sent_on_$HOSTNAME</screen> 3868 </example> 3869 <para> 3870 will cause NeoMutt to save outgoing messages to a folder named 3871 <quote>sent_on_kremvax</quote> if the environment variable 3872 <literal>$HOSTNAME</literal> is set to <quote>kremvax.</quote> (See 3873 <link linkend="record">$record</link> for details.) 3874 </para> 3875 <para> 3876 NeoMutt expands the variable when it is assigned, not when it is used. 3877 If the value of a variable on the right-hand side of an assignment 3878 changes after the assignment, the variable on the left-hand side will 3879 not be affected. 3880 </para> 3881 <para> 3882 The commands understood by NeoMutt are explained in the next 3883 paragraphs. For a complete list, see the 3884 <link linkend="commands">command reference</link>. 3885 </para> 3886 <para> 3887 All configuration files are expected to be in the current locale as 3888 specified by the <link linkend="charset">$charset</link> variable which 3889 doesn't have a default value since it's determined by NeoMutt at 3890 startup. If a configuration file is not encoded in the same character 3891 set the <link linkend="config-charset">$config_charset</link> variable 3892 should be used: all lines starting with the next are recoded from 3893 <link linkend="config-charset">$config_charset</link> to 3894 <link linkend="charset">$charset</link>. 3895 </para> 3896 <para> 3897 This mechanism should be avoided if possible as it has the following 3898 implications: 3899 </para> 3900 <itemizedlist> 3901 <listitem> 3902 <para> 3903 These variables should be set early in a configuration file with 3904 <link linkend="charset">$charset</link> preceding 3905 <link linkend="config-charset">$config_charset</link> so NeoMutt 3906 knows what character set to convert to. 3907 </para> 3908 </listitem> 3909 <listitem> 3910 <para> 3911 If <link linkend="config-charset">$config_charset</link> is set, it 3912 should be set in each configuration file because the value is 3913 global and <emphasis>not</emphasis> per configuration file. 3914 </para> 3915 </listitem> 3916 <listitem> 3917 <para> 3918 Because NeoMutt first recodes a line before it attempts to parse 3919 it, a conversion introducing question marks or other characters as 3920 part of errors (unconvertable characters, transliteration) may 3921 introduce syntax errors or silently change the meaning of certain 3922 tokens (e.g. inserting question marks into regular expressions). 3923 </para> 3924 </listitem> 3925 </itemizedlist> 3926 </sect1> 3927 3928 <sect1 id="addrgroup"> 3929 <title>Address Groups</title> 3930 <para> 3931 Usage: 3932 </para> 3933 <cmdsynopsis> 3934 <command>group</command> 3935 <arg choice="opt" rep="repeat"> 3936 <option>-group</option> 3937 <replaceable class="parameter">name</replaceable> 3938 </arg> 3939 <group choice="req"> 3940 <arg choice="plain" rep="repeat"> 3941 <option>-rx</option> 3942 <replaceable class="parameter">expr</replaceable> 3943 </arg> 3944 <arg choice="plain" rep="repeat"> 3945 <option>-addr</option> 3946 <replaceable class="parameter">expr</replaceable> 3947 </arg> 3948 </group> 3949 <command>ungroup</command> 3950 <arg choice="opt" rep="repeat"> 3951 <option>-group</option> 3952 <replaceable class="parameter">name</replaceable> 3953 </arg> 3954 <group choice="req"> 3955 <arg choice="plain"> 3956 <replaceable class="parameter">*</replaceable> 3957 </arg> 3958 <arg choice="plain" rep="repeat"> 3959 <option>-rx</option> 3960 <replaceable class="parameter">expr</replaceable> 3961 </arg> 3962 <arg choice="plain" rep="repeat"> 3963 <option>-addr</option> 3964 <replaceable class="parameter">expr</replaceable> 3965 </arg> 3966 </group> 3967 </cmdsynopsis> 3968 <para> 3969 NeoMutt supports grouping addresses logically into named groups. An 3970 address or address pattern can appear in several groups at the same 3971 time. These groups can be used in 3972 <link linkend="patterns">patterns</link> (for searching, limiting and 3973 tagging) and in hooks by using group patterns. This can be useful to 3974 classify mail and take certain actions depending on in what groups the 3975 message is. For example, the NeoMutt user's mailing list would fit into 3976 the categories <quote>mailing list</quote> and 3977 <quote>NeoMutt-related</quote>. Using 3978 <link linkend="send-hook"><literal>send-hook</literal></link>, the 3979 sender can be set to a dedicated one for writing mailing list messages, 3980 and the signature could be set to a NeoMutt-related one for writing to 3981 a NeoMutt list – for other lists, the list sender setting still applies 3982 but a different signature can be selected. Or, given a group only 3983 containing recipients known to accept encrypted mail, 3984 <quote>auto-encryption</quote> can be achieved easily. 3985 </para> 3986 <para> 3987 The <command>group</command> command is used to directly add either 3988 addresses or regular expressions to the specified group or groups. The 3989 different categories of arguments to the <command>group</command> 3990 command can be in any order. The flags <literal>-rx</literal> and 3991 <literal>-addr</literal> specify what the following strings (that 3992 cannot begin with a hyphen) should be interpreted as: either a regular 3993 expression or an email address, respectively. 3994 </para> 3995 <para> 3996 These address groups can also be created implicitly by the 3997 <link linkend="alias"><command>alias</command></link>, 3998 <link linkend="lists"><command>lists</command></link>, 3999 <link linkend="lists"><command>subscribe</command></link> and 4000 <link linkend="alternates"><command>alternates</command></link> 4001 commands by specifying the optional <literal>-group</literal> option. 4002 For example, 4003 </para> 4004 4005<screen> 4006alternates -group me address1 address2 4007alternates -group me -group work address3 4008</screen> 4009 4010 <para> 4011 would create a group named <quote>me</quote> which contains all your 4012 addresses and a group named <quote>work</quote> which contains only 4013 your work address <emphasis>address3</emphasis>. Besides many other 4014 possibilities, this could be used to automatically mark your own 4015 messages in a mailing list folder as read or use a special signature 4016 for work-related messages. 4017 </para> 4018 <para> 4019 The <command>ungroup</command> command is used to remove addresses or 4020 regular expressions from the specified group or groups. The syntax is 4021 similar to the <command>group</command> command, however the special 4022 character <literal>*</literal> can be used to empty a group of all of 4023 its contents. As soon as a group gets empty because all addresses and 4024 regular expressions have been removed, it'll internally be removed, too 4025 (i.e. there cannot be an empty group). When removing regular 4026 expressions from a group, the pattern must be specified exactly as 4027 given to the <command>group</command> command or 4028 <literal>-group</literal> argument. 4029 </para> 4030 </sect1> 4031 4032 <sect1 id="alias"> 4033 <title>Defining/Using Aliases</title> 4034 <para> 4035 Usage: 4036 </para> 4037 <cmdsynopsis> 4038 <command>alias</command> 4039 <arg choice="opt" rep="repeat"> 4040 <option>-group</option> 4041 <replaceable class="parameter">name</replaceable> 4042 </arg> 4043 <arg choice="plain"> 4044 <replaceable class="parameter">key</replaceable> 4045 </arg> 4046 <arg choice="plain"> 4047 <replaceable class="parameter">address</replaceable> 4048 </arg> 4049 <arg choice="opt" rep="repeat"> 4050 <replaceable class="parameter">, address</replaceable> 4051 </arg> 4052 <arg choice="opt"> 4053 <replaceable class="parameter"># comment</replaceable> 4054 </arg> 4055 <command>unalias</command> 4056 <arg choice="opt" rep="repeat"> 4057 <option>-group</option> 4058 <replaceable>name</replaceable> 4059 </arg> 4060 <group choice="req"> 4061 <arg choice="plain"> 4062 <replaceable class="parameter">*</replaceable> 4063 </arg> 4064 <arg choice="plain" rep="repeat"> 4065 <replaceable class="parameter">key</replaceable> 4066 </arg> 4067 </group> 4068 </cmdsynopsis> 4069 <para> 4070 It's usually very cumbersome to remember or type out the address of 4071 someone you are communicating with. NeoMutt allows you to create 4072 <quote>aliases</quote> which map a short string to a full address. 4073 </para> 4074 <note> 4075 <para> 4076 If you want to create an alias for more than one address, you 4077 <emphasis>must</emphasis> separate the addresses with a comma 4078 (<quote>,</quote>). 4079 </para> 4080 </note> 4081 <para> 4082 The optional <literal>-group</literal> argument to 4083 <command>alias</command> causes the aliased address(es) to be added to 4084 the named <emphasis>group</emphasis>. 4085 </para> 4086 <para> 4087 To add an alias: 4088 </para> 4089 4090<screen> 4091<emphasis role="comment"># Some aliases, one with a comment</emphasis> 4092alias alan Alan Jones <alan@example.com> 4093alias briony Briony Williams <bw@example.com> 4094alias jim James Smith <js@example.com> <emphasis role="comment"># Pointy-haired boss</emphasis> 4095 4096<emphasis role="comment"># An alias that references two other aliases</emphasis> 4097alias friends alan, briony 4098</screen> 4099 4100 <para> 4101 To remove an alias or aliases (<quote>*</quote> means all aliases): 4102 </para> 4103 4104<screen> 4105unalias muttdude 4106unalias * 4107</screen> 4108 4109 <para> 4110 Unlike other mailers, NeoMutt doesn't require aliases to be defined in 4111 a special file. The <command>alias</command> command can appear 4112 anywhere in a configuration file, as long as this file is 4113 <link linkend="source"><command>sourced</command></link>. Consequently, 4114 you can have multiple alias files, or you can have all aliases defined 4115 in your <literal>.neomuttrc</literal>. 4116 </para> 4117 <para> 4118 On the other hand, the 4119 <link linkend="create-alias"><literal><create-alias></literal></link> 4120 function can use only one file, the one pointed to by the 4121 <link linkend="alias-file">$alias_file</link> variable (which is 4122 <literal>~/.neomuttrc</literal> by default). This file is not special 4123 either, in the sense that NeoMutt will happily append aliases to any 4124 file, but in order for the new aliases to take effect you need to 4125 explicitly <link linkend="source"><command>source</command></link> this 4126 file too. 4127 </para> 4128 <example id="ex-alias-external"> 4129 <title>Configuring external alias files</title> 4130 4131<screen> 4132source /usr/local/share/NeoMutt.aliases 4133source ~/.mail_aliases 4134set alias_file=~/.mail_aliases 4135</screen> 4136 4137 </example> 4138 <para> 4139 To use aliases, you merely use the alias at any place in NeoMutt where 4140 NeoMutt prompts for addresses, such as the <emphasis>To:</emphasis> or 4141 <emphasis>Cc:</emphasis> prompt. You can also enter aliases in your 4142 editor at the appropriate headers if you have the 4143 <link linkend="edit-headers">$edit_headers</link> variable set. 4144 </para> 4145 <para> 4146 In addition, at the various address prompts, you can use the tab 4147 character to expand a partial alias to the full alias. If there are 4148 multiple matches, NeoMutt will bring up a menu with the matching 4149 aliases. In order to be presented with the full list of aliases, you 4150 must hit tab without a partial alias, such as at the beginning of the 4151 prompt or after a comma denoting multiple addresses. 4152 </para> 4153 <para> 4154 In the alias menu, you can select as many aliases as you want with the 4155 <literal>tag-entry</literal> key (default: <Space> or t), and use 4156 the <emphasis>exit</emphasis> key (default: q) to return to the address 4157 prompt. 4158 </para> 4159 </sect1> 4160 4161 <sect1 id="bind"> 4162 <title>Changing the Default Key Bindings</title> 4163 <para> 4164 Usage: 4165 </para> 4166 <cmdsynopsis> 4167 <command>bind</command> 4168 <arg choice="plain"> 4169 <replaceable class="parameter">map</replaceable> 4170 </arg> 4171 <arg choice="opt" rep="repeat"> 4172 <replaceable class="parameter">,map</replaceable> 4173 </arg> 4174 <arg choice="plain"> 4175 <replaceable class="parameter">key</replaceable> 4176 </arg> 4177 <arg choice="plain"> 4178 <replaceable class="parameter">function</replaceable> 4179 </arg> 4180 <command>unbind</command> 4181 <group choice="req"> 4182 <arg choice="plain"> 4183 <replaceable class="parameter">*</replaceable> 4184 </arg> 4185 <arg choice="plain"> 4186 <replaceable class="parameter">map</replaceable> 4187 </arg> 4188 <arg choice="opt" rep="repeat"> 4189 <replaceable class="parameter">,map</replaceable> 4190 </arg> 4191 </group> 4192 <group choice="opt"> 4193 <arg choice="plain"> 4194 <replaceable class="parameter">key</replaceable> 4195 </arg> 4196 </group> 4197 </cmdsynopsis> 4198 <para> 4199 This command allows you to change the default key bindings (operation 4200 invoked when pressing a key). 4201 </para> 4202 <para> 4203 <emphasis>map</emphasis> specifies in which menu the binding belongs. 4204 Multiple maps may be specified by separating them with commas (no 4205 additional whitespace is allowed). The currently defined maps are: 4206 </para> 4207 <note> 4208 <para> 4209 Missing key sequence in unbind command means unibind all bindings in menus 4210 given in <emphasis>map</emphasis>. 4211 </para> 4212 </note> 4213 <anchor id="maps" /> 4214 <variablelist> 4215 <varlistentry> 4216 <term>generic</term> 4217 <listitem> 4218 <para> 4219 This is not a real menu, but is used as a fallback for all of the 4220 other menus except for the pager and editor modes. If a key is 4221 not defined in another menu, NeoMutt will look for a binding to 4222 use in this menu. This allows you to bind a key to a certain 4223 function in multiple menus instead of having multiple 4224 <command>bind</command> statements to accomplish the same task. 4225 </para> 4226 </listitem> 4227 </varlistentry> 4228 <varlistentry> 4229 <term>alias</term> 4230 <listitem> 4231 <para> 4232 The alias menu is the list of your personal aliases as defined in 4233 your <literal>.neomuttrc</literal>. It is the mapping from 4234 a short alias name to the full email address(es) of the 4235 recipient(s). 4236 </para> 4237 </listitem> 4238 </varlistentry> 4239 <varlistentry> 4240 <term>attach</term> 4241 <listitem> 4242 <para> 4243 The attachment menu is used to access the attachments on received 4244 messages. 4245 </para> 4246 </listitem> 4247 </varlistentry> 4248 <varlistentry> 4249 <term>browser</term> 4250 <listitem> 4251 <para> 4252 The browser is used for both browsing the local directory 4253 structure, and for listing all of your incoming mailboxes. 4254 </para> 4255 </listitem> 4256 </varlistentry> 4257 <varlistentry> 4258 <term>editor</term> 4259 <listitem> 4260 <para> 4261 The editor is used to allow the user to enter a single line of 4262 text, such as the <emphasis>To</emphasis> or 4263 <emphasis>Subject</emphasis> prompts in the 4264 <literal>compose</literal> menu. 4265 </para> 4266 </listitem> 4267 </varlistentry> 4268 <varlistentry> 4269 <term>index</term> 4270 <listitem> 4271 <para> 4272 The index is the list of messages contained in a mailbox. 4273 </para> 4274 </listitem> 4275 </varlistentry> 4276 <varlistentry> 4277 <term>compose</term> 4278 <listitem> 4279 <para> 4280 The compose menu is the screen used when sending a new message. 4281 </para> 4282 </listitem> 4283 </varlistentry> 4284 <varlistentry> 4285 <term>pager</term> 4286 <listitem> 4287 <para> 4288 The pager is the mode used to display message/attachment data, 4289 and help listings. 4290 </para> 4291 </listitem> 4292 </varlistentry> 4293 <varlistentry> 4294 <term>pgp</term> 4295 <listitem> 4296 <para> 4297 The pgp menu is used to select the OpenPGP keys used to encrypt 4298 outgoing messages. 4299 </para> 4300 </listitem> 4301 </varlistentry> 4302 <varlistentry> 4303 <term>smime</term> 4304 <listitem> 4305 <para> 4306 The smime menu is used to select the OpenSSL certificates used to 4307 encrypt outgoing messages. 4308 </para> 4309 </listitem> 4310 </varlistentry> 4311 <varlistentry> 4312 <term>postpone</term> 4313 <listitem> 4314 <para> 4315 The postpone menu is similar to the index menu, except is used 4316 when recalling a message the user was composing, but saved until 4317 later. 4318 </para> 4319 </listitem> 4320 </varlistentry> 4321 <varlistentry> 4322 <term>query</term> 4323 <listitem> 4324 <para> 4325 The query menu is the browser for results returned by 4326 <link linkend="query-command">$query_command</link>. 4327 </para> 4328 </listitem> 4329 </varlistentry> 4330 <varlistentry> 4331 <term>mix</term> 4332 <listitem> 4333 <para> 4334 The mixmaster screen is used to select remailer options for 4335 outgoing messages (if NeoMutt is compiled with Mixmaster 4336 support). 4337 </para> 4338 </listitem> 4339 </varlistentry> 4340 </variablelist> 4341 <para> 4342 <emphasis>key</emphasis> is the key (or key sequence) you wish to bind. 4343 To specify a control character, use the sequence 4344 <emphasis>\Cx</emphasis>, where <emphasis>x</emphasis> is the letter of 4345 the control character (for example, to specify control-A use 4346 <quote>\Ca</quote>). Note that the case of <emphasis>x</emphasis> as 4347 well as <emphasis>\C</emphasis> is ignored, so that 4348 <emphasis>\CA</emphasis>, <emphasis>\Ca</emphasis>, 4349 <emphasis>\cA</emphasis> and <emphasis>\ca</emphasis> are all 4350 equivalent. An alternative form is to specify the key as a three digit 4351 octal number prefixed with a <quote>\</quote> (for example 4352 <emphasis>\177</emphasis> is equivalent to <emphasis>\c?</emphasis>). 4353 In addition, <emphasis>key</emphasis> may be a symbolic name as shown 4354 in <xref linkend="tab-key-names" />. 4355 </para> 4356 4357 <table id="tab-key-names"> 4358 <title>Symbolic key names</title> 4359 <tgroup cols="2"> 4360 <thead> 4361 <row> 4362 <entry>Symbolic name</entry> 4363 <entry>Meaning</entry> 4364 </row> 4365 </thead> 4366 <tbody> 4367 <row> 4368 <entry>\t</entry> 4369 <entry>tab</entry> 4370 </row> 4371 <row> 4372 <entry><tab></entry> 4373 <entry>tab</entry> 4374 </row> 4375 <row> 4376 <entry><backtab></entry> 4377 <entry>backtab / shift-tab</entry> 4378 </row> 4379 <row> 4380 <entry>\r</entry> 4381 <entry>carriage return</entry> 4382 </row> 4383 <row> 4384 <entry>\n</entry> 4385 <entry>newline</entry> 4386 </row> 4387 <row> 4388 <entry>\e</entry> 4389 <entry>escape/alt</entry> 4390 </row> 4391 <row> 4392 <entry><esc></entry> 4393 <entry>escape/alt</entry> 4394 </row> 4395 <row> 4396 <entry><up></entry> 4397 <entry>up arrow</entry> 4398 </row> 4399 <row> 4400 <entry><down></entry> 4401 <entry>down arrow</entry> 4402 </row> 4403 <row> 4404 <entry><left></entry> 4405 <entry>left arrow</entry> 4406 </row> 4407 <row> 4408 <entry><right></entry> 4409 <entry>right arrow</entry> 4410 </row> 4411 <row> 4412 <entry><pageup></entry> 4413 <entry>Page Up</entry> 4414 </row> 4415 <row> 4416 <entry><pagedown></entry> 4417 <entry>Page Down</entry> 4418 </row> 4419 <row> 4420 <entry><backspace></entry> 4421 <entry>Backspace</entry> 4422 </row> 4423 <row> 4424 <entry><delete></entry> 4425 <entry>Delete</entry> 4426 </row> 4427 <row> 4428 <entry><insert></entry> 4429 <entry>Insert</entry> 4430 </row> 4431 <row> 4432 <entry><enter></entry> 4433 <entry>Enter</entry> 4434 </row> 4435 <row> 4436 <entry><return></entry> 4437 <entry>Return</entry> 4438 </row> 4439 <row> 4440 <entry><home></entry> 4441 <entry>Home</entry> 4442 </row> 4443 <row> 4444 <entry><end></entry> 4445 <entry>End</entry> 4446 </row> 4447 <row> 4448 <entry><space></entry> 4449 <entry>Space bar</entry> 4450 </row> 4451 <row> 4452 <entry><f1></entry> 4453 <entry>function key 1</entry> 4454 </row> 4455 <row> 4456 <entry><f10></entry> 4457 <entry>function key 10</entry> 4458 </row> 4459 </tbody> 4460 </tgroup> 4461 </table> 4462 <para> 4463 The <literal><what-key></literal> function can be used to explore 4464 keycode and symbolic names for other keys on your keyboard. Executing 4465 this function will display information about each key pressed, until 4466 terminated by <literal>^G</literal>. 4467 </para> 4468 <para> 4469 <emphasis>key</emphasis> does not need to be enclosed in quotes unless 4470 it contains a space (<quote> </quote>) or semi-colon 4471 (<quote>;</quote>). 4472 </para> 4473 <para> 4474 <emphasis>function</emphasis> specifies which action to take when 4475 <emphasis>key</emphasis> is pressed. For a complete list of functions, 4476 see the <link linkend="functions">reference</link>. Note that the 4477 <command>bind</command> expects <emphasis>function</emphasis> to be 4478 specified without angle brackets. 4479 </para> 4480 <para> 4481 The special function <literal><noop></literal> unbinds the 4482 specified key sequence. 4483 </para> 4484 4485 <sect2 id="bind-warnings"> 4486 <title>Warnings about Duplicated Bindings</title> 4487 <para> 4488 Due to a limitation of NeoMutt, creating key bindings, or macros, 4489 will overwrite existing mappings with similar, shorter, names. 4490 </para> 4491 4492<screen> 4493bind index g group-reply 4494bind index gg first-entry 4495</screen> 4496 4497 <para> 4498 In this example, the <literal>g</literal> binding will be overwritten 4499 and cannot be used. Newer versions of NeoMutt will warn the user 4500 about this. 4501 </para> 4502 <para> 4503 To avoid warnings on startup, first set the shorter binding to 4504 <literal>noop</literal> (no operation). 4505 </para> 4506 4507<screen> 4508bind index g noop 4509bind index gg first-entry 4510</screen> 4511 4512 <para> 4513 The same is also possible using <literal>unbind</literal>. 4514 </para> 4515 4516<screen> 4517unbind index g 4518bind index gg first-entry 4519</screen> 4520 4521 </sect2> 4522 4523 <sect2 id="stty"> 4524 <title>Terminal Keybindings</title> 4525 <para> 4526 Some key bindings are controlled by the terminal, and so by 4527 default can't be bound inside NeoMutt. These may include 4528 <literal>^C</literal>, <literal>^\</literal>, <literal>^Q</literal>, 4529 <literal>^S</literal>, <literal>^Z</literal>, and on BSD/Mac 4530 <literal>^Y</literal>. These terminal settings can be viewed and 4531 changed using the <literal>stty</literal> program. 4532 </para> 4533 <para> 4534 <quote><literal>stty -a</literal></quote> will list the bound 4535 characters (not all of them affect NeoMutt), and what actions they 4536 take when pressed. For example, 4537 you may see <quote><literal>intr = ^C</literal></quote> in its 4538 output. This means typing <literal>^C</literal> will send an 4539 interrupt signal. <quote><literal>quit = ^\</literal></quote> 4540 means typing <literal>^\</literal> (commonly also 4541 <literal>^4</literal>) will send a quit signal. 4542 </para> 4543 <para> 4544 To unbind a key from an action, you invoke <quote>stty action 4545 undef</quote>. For example, <quote><literal>stty quit 4546 undef</literal></quote> will unbind <literal>^\</literal> (and 4547 <literal>^4</literal>) from sending the quit signal. Once unbound 4548 (e.g, by placing that line in your .bashrc, or in a NeoMutt wrapper 4549 script/function) you can use the key sequence in your NeoMutt 4550 bindings. 4551 </para> 4552 </sect2> 4553 </sect1> 4554 4555 <sect1 id="cd"> 4556 <title>Changing the current working directory</title> 4557 <para>Usage:</para> 4558 <cmdsynopsis> 4559 <command>cd</command> 4560 <arg choice="plain"> 4561 <replaceable class="parameter">directory</replaceable> 4562 </arg> 4563 </cmdsynopsis> 4564 <para> 4565 The <literal>cd</literal> command changes NeoMutt's current working directory. 4566 This affects commands and functions like <literal>source</literal>, 4567 <literal>change-folder</literal>, and <literal>save-entry</literal> that use 4568 relative paths. Using <literal>cd</literal> without directory changes to your 4569 home directory. 4570 </para> 4571 </sect1> 4572 4573 <sect1 id="charset-hook"> 4574 <title>Defining Aliases for Character Sets</title> 4575 <anchor id="iconv-hook" /> 4576 <para> 4577 Usage: 4578 </para> 4579 <cmdsynopsis> 4580 <command>charset-hook</command> 4581 <arg choice="plain"> 4582 <replaceable class="parameter">alias</replaceable> 4583 </arg> 4584 <arg choice="plain"> 4585 <replaceable class="parameter">charset</replaceable> 4586 </arg> 4587 <command>iconv-hook</command> 4588 <arg choice="plain"> 4589 <replaceable class="parameter">charset</replaceable> 4590 </arg> 4591 <arg choice="plain"> 4592 <replaceable class="parameter">local-charset</replaceable> 4593 </arg> 4594 </cmdsynopsis> 4595 <para> 4596 The <command>charset-hook</command> command defines an alias for 4597 a character set. This is useful to properly display messages which are 4598 tagged with a character set name not known to NeoMutt. 4599 </para> 4600 <para> 4601 The <command>iconv-hook</command> command defines a system-specific 4602 name for a character set. This is helpful when your systems character 4603 conversion library insists on using strange, system-specific names for 4604 character sets. 4605 </para> 4606 </sect1> 4607 4608 <sect1 id="folder-hook"> 4609 <title>Setting Variables Based Upon Mailbox</title> 4610 <para> 4611 Usage: 4612 </para> 4613 <cmdsynopsis> 4614 <command>folder-hook</command> 4615 <arg choice="opt"> 4616 <replaceable class="parameter">-noregex</replaceable> 4617 </arg> 4618 <arg choice="plain"> 4619 <replaceable class="parameter">pattern</replaceable> 4620 </arg> 4621 <arg choice="plain"> 4622 <replaceable class="parameter">command</replaceable> 4623 </arg> 4624 </cmdsynopsis> 4625 <para> 4626 It is often desirable to change settings based on which mailbox you are 4627 reading. The <command>folder-hook</command> command provides a method 4628 by which you can execute any configuration command. 4629 The <emphasis>command</emphasis> is executed before loading any mailboxes 4630 matching <emphasis>pattern</emphasis>. The <emphasis>-noregex</emphasis> 4631 switch controls whether <emphasis>pattern</emphasis> is matched using 4632 a simple string comparison or a full regex match. 4633 If a mailbox matches multiple <command>folder-hook</command>s, they are 4634 executed in the order given in the <literal>.neomuttrc</literal>. 4635 </para> 4636 <para> 4637 The regex parameter has 4638 <link linkend="shortcuts">mailbox shortcut</link> expansion performed 4639 on the first character. See <xref linkend="mailbox-hook" /> for more 4640 details. 4641 </para> 4642 <note> 4643 <para> 4644 If you use the <quote>!</quote> shortcut for 4645 <link linkend="spool-file">$spool_file</link> at the beginning of the 4646 pattern, you must place it inside of double or single quotes in order 4647 to distinguish it from the logical <emphasis>not</emphasis> operator 4648 for the expression. 4649 </para> 4650 </note> 4651 <note> 4652 <para> 4653 Settings are <emphasis>not</emphasis> restored when you leave the 4654 mailbox. For example, a command action to perform is to change the 4655 sorting method based upon the mailbox being read: 4656 </para> 4657 <screen>folder-hook work "set sort=threads"</screen> 4658 <para> 4659 However, the sorting method is not restored to its previous value 4660 when reading a different mailbox. To specify 4661 a <emphasis>default</emphasis> command, use the pattern 4662 <quote>.</quote> before other <command>folder-hook</command>s 4663 adjusting a value on a per-folder basis because 4664 <command>folder-hook</command>s are evaluated in the order given in 4665 the configuration file. 4666 </para> 4667 </note> 4668 <note> 4669 <para> 4670 The keyboard buffer will not be processed until after all hooks are 4671 run; multiple <link linkend="push">push</link> or 4672 <link linkend="exec">exec</link> commands will end up being processed 4673 in reverse order. 4674 </para> 4675 </note> 4676 <para> 4677 The following example will set the <link linkend="sort">sort</link> 4678 variable to <literal>date-sent</literal> for all folders but to 4679 <literal>threads</literal> for all folders containing 4680 <quote>work</quote> in their name. 4681 </para> 4682 <example id="ex-folder-sorting"> 4683 <title>Setting sort method based on mailbox name</title> 4684 4685<screen> 4686folder-hook . "set sort=date-sent" 4687folder-hook work "set sort=threads" 4688</screen> 4689 4690 </example> 4691 </sect1> 4692 4693 <sect1 id="macro"> 4694 <title>Keyboard Macros</title> 4695 <para> 4696 Usage: 4697 </para> 4698 <cmdsynopsis> 4699 <command>macro</command> 4700 <arg choice="plain"> 4701 <replaceable class="parameter">menu</replaceable> 4702 </arg> 4703 <arg choice="opt" rep="repeat"> 4704 <replaceable class="parameter">,menu</replaceable> 4705 </arg> 4706 <arg choice="plain"> 4707 <replaceable class="parameter">key</replaceable> 4708 </arg> 4709 <arg choice="plain"> 4710 <replaceable class="parameter">sequence</replaceable> 4711 </arg> 4712 <arg choice="opt"> 4713 <replaceable class="parameter">description</replaceable> 4714 </arg> 4715 <command>unmacro</command> 4716 <group choice="req"> 4717 <arg choice="plain"> 4718 <replaceable class="parameter">*</replaceable> 4719 </arg> 4720 <arg choice="plain"> 4721 <replaceable class="parameter">map</replaceable> 4722 </arg> 4723 <arg choice="opt" rep="repeat"> 4724 <replaceable class="parameter">,map</replaceable> 4725 </arg> 4726 </group> 4727 <group choice="opt"> 4728 <arg choice="plain"> 4729 <replaceable class="parameter">key</replaceable> 4730 </arg> 4731 </group> 4732 4733 </cmdsynopsis> 4734 <para> 4735 Macros are useful when you would like a single key to perform a series 4736 of actions. When you press <emphasis>key</emphasis> in menu 4737 <emphasis>menu</emphasis>, NeoMutt will behave as if you had typed 4738 <emphasis>sequence</emphasis>. So if you have a common sequence of 4739 commands you type, you can create a macro to execute those commands 4740 with a single key or fewer keys. 4741 </para> 4742 <para> 4743 <emphasis>menu</emphasis> is the <link linkend="maps">map</link> which 4744 the macro will be bound in. Multiple maps may be specified by 4745 separating multiple menu arguments by commas. Whitespace may not be 4746 used in between the menu arguments and the commas separating them. 4747 </para> 4748 <para> 4749 <emphasis>key</emphasis> and <emphasis>sequence</emphasis> are expanded 4750 by the same rules as the <link linkend="bind">key bindings</link> with 4751 some additions. The first is that control characters in 4752 <emphasis>sequence</emphasis> can also be specified as 4753 <emphasis>^x</emphasis>. In order to get a caret (<quote>^</quote>) 4754 you need to use <emphasis>^^</emphasis>. Secondly, to specify a certain 4755 key such as <emphasis>up</emphasis> or to invoke a function directly, 4756 you can use the format <emphasis><key name></emphasis> and 4757 <emphasis><function name></emphasis>. For a listing of key names 4758 see the section on <link linkend="bind">key bindings</link>. Functions 4759 are listed in the <link linkend="functions">reference</link>. 4760 </para> 4761 <para> 4762 The advantage with using function names directly is that the macros 4763 will work regardless of the current key bindings, so they are not 4764 dependent on the user having particular key definitions. This makes 4765 them more robust and portable, and also facilitates defining of macros 4766 in files used by more than one user (e.g., the system neomuttrc). 4767 </para> 4768 <para> 4769 Optionally you can specify a descriptive text after 4770 <emphasis>sequence</emphasis>, which is shown in the help screens if 4771 they contain a description. 4772 </para> 4773 <note> 4774 <para> 4775 Macro definitions (if any) listed in the help screen(s), are silently 4776 truncated at the screen width, and are not wrapped. 4777 </para> 4778 </note> 4779 <note> 4780 <para> 4781 Missing key sequence in unmacro command means unmacro all macros in menus 4782 given in <emphasis>menu</emphasis>. 4783 </para> 4784 </note> 4785 </sect1> 4786 4787 <sect1 id="color"> 4788 <title>Using Color and Mono Video Attributes</title> 4789 <para> 4790 Usage: 4791 </para> 4792 <cmdsynopsis> 4793 <command>color</command> 4794 <arg choice="opt"> 4795 <option>compose</option> 4796 </arg> 4797 <arg choice="plain"> 4798 <replaceable class="parameter">object</replaceable> 4799 </arg> 4800 <arg choice="opt" rep="repeat"> 4801 <replaceable class="parameter">attribute</replaceable> 4802 </arg> 4803 <arg choice="plain"> 4804 <replaceable class="parameter">foreground</replaceable> 4805 </arg> 4806 <arg choice="plain"> 4807 <replaceable class="parameter">background</replaceable> 4808 </arg> 4809 <command>color</command> 4810 <arg choice="plain"> 4811 <replaceable class="parameter">pattern-object</replaceable> 4812 </arg> 4813 <arg choice="opt" rep="repeat"> 4814 <replaceable class="parameter">attribute</replaceable> 4815 </arg> 4816 <arg choice="plain"> 4817 <replaceable class="parameter">foreground</replaceable> 4818 </arg> 4819 <arg choice="plain"> 4820 <replaceable class="parameter">background</replaceable> 4821 </arg> 4822 <arg choice="plain"> 4823 <replaceable class="parameter">pattern</replaceable> 4824 </arg> 4825 <command>color</command> 4826 <arg choice="plain"> 4827 <replaceable class="parameter">regex-object</replaceable> 4828 </arg> 4829 <arg choice="opt" rep="repeat"> 4830 <replaceable class="parameter">attribute</replaceable> 4831 </arg> 4832 <arg choice="plain"> 4833 <replaceable class="parameter">foreground</replaceable> 4834 </arg> 4835 <arg choice="plain"> 4836 <replaceable class="parameter">background</replaceable> 4837 </arg> 4838 <arg choice="plain"> 4839 <replaceable class="parameter">regex</replaceable> 4840 </arg> 4841 <command>color</command> 4842 <arg choice="plain"> 4843 <option>status</option> 4844 </arg> 4845 <arg choice="opt" rep="repeat"> 4846 <replaceable class="parameter">attribute</replaceable> 4847 </arg> 4848 <arg choice="plain"> 4849 <replaceable class="parameter">foreground</replaceable> 4850 </arg> 4851 <arg choice="plain"> 4852 <replaceable class="parameter">background</replaceable> 4853 </arg> 4854 <group choice="opt"> 4855 <arg choice="plain"> 4856 <replaceable class="parameter">regex</replaceable> 4857 </arg> 4858 <group choice="opt"> 4859 <arg choice="plain"> 4860 <replaceable class="parameter">num</replaceable> 4861 </arg> 4862 </group> 4863 </group> 4864 <command>uncolor</command> 4865 <arg choice="opt"> 4866 <option>compose</option> 4867 </arg> 4868 <arg choice="plain"> 4869 <replaceable class="parameter">object</replaceable> 4870 </arg> 4871 <command>uncolor</command> 4872 <arg choice="plain"> 4873 <replaceable class="parameter">pattern-object</replaceable> 4874 </arg> 4875 <group choice="req"> 4876 <arg choice="plain"> 4877 <replaceable>pattern</replaceable> 4878 </arg> 4879 <arg choice="plain"> 4880 <replaceable>*</replaceable> 4881 </arg> 4882 </group> 4883 <command>uncolor</command> 4884 <arg choice="plain"> 4885 <replaceable class="parameter">regex-object</replaceable> 4886 </arg> 4887 <group choice="req"> 4888 <arg choice="plain"> 4889 <replaceable>regex</replaceable> 4890 </arg> 4891 <arg choice="plain"> 4892 <replaceable>*</replaceable> 4893 </arg> 4894 </group> 4895 <command>uncolor</command> 4896 <arg choice="plain"> 4897 <option>status</option> 4898 </arg> 4899 <group choice="req"> 4900 <arg choice="plain"> 4901 <replaceable>regex</replaceable> 4902 </arg> 4903 <arg choice="plain"> 4904 <replaceable>*</replaceable> 4905 </arg> 4906 </group> 4907 </cmdsynopsis> 4908 <para> 4909 If your terminal supports color, you can spice up NeoMutt by creating 4910 your own <link linkend="color-style">color scheme</link>. 4911 </para> 4912 <para> 4913 The types of objects that can be colored fall into two categories: 4914 <link linkend="color-simple">Simple Colors</link> such as the 4915 highlight in the index, and <link linkend="color-lists">Color Lists</link> 4916 such as the status bar. These lists can created complexing coloring 4917 rules. 4918 </para> 4919 4920 <sect2 id="color-style"> 4921 <title>Color Style</title> 4922 <para> 4923 Objects in NeoMutt can be given colors and attributes to make things 4924 easier to find and use. 4925 </para> 4926 <note> 4927 <para> 4928 Objects must be given <emphasis>both</emphasis> a foreground and 4929 background color (it is not possible to specify one or the other). 4930 </para> 4931 </note> 4932 <para> 4933 Colors can be specified in two ways, using their name 4934 such as <literal>green</literal>, <literal>blue</literal>, 4935 or by their number in the palette, 4936 such as <literal>color12</literal>, <literal>color207</literal> 4937 (the palette consists of the 4938 <ulink url="https://web.archive.org/web/20190712111427/https://jonasjacek.github.io/colors/">256 Xterm colors</ulink>). 4939 </para> 4940 <para> 4941 Named colours may also be prefixed by a <emphasis>modifier</emphasis>. 4942 <literal>bright</literal> or <literal>light</literal> will make the 4943 color boldfaced or light (e.g., <literal>brightred</literal>). 4944 <literal>alert</literal> to make a blinking/alert color (e.g., 4945 <literal>alertred</literal>). 4946 </para> 4947 <para> 4948 The precise behavior depends on the terminal and its configuration. 4949 In particular, the boldfaced/light difference and such background 4950 colors may be available only for terminals configured with at least 4951 16 colors, as specified by the <literal>$TERM</literal> 4952 environment variable. 4953 </para> 4954 <para> 4955 <emphasis>foreground</emphasis> and <emphasis>background</emphasis> 4956 can be one of the following: 4957 </para> 4958 <itemizedlist> 4959 <listitem> 4960 <para> 4961 white 4962 </para> 4963 </listitem> 4964 <listitem> 4965 <para> 4966 black 4967 </para> 4968 </listitem> 4969 <listitem> 4970 <para> 4971 green 4972 </para> 4973 </listitem> 4974 <listitem> 4975 <para> 4976 magenta 4977 </para> 4978 </listitem> 4979 <listitem> 4980 <para> 4981 blue 4982 </para> 4983 </listitem> 4984 <listitem> 4985 <para> 4986 cyan 4987 </para> 4988 </listitem> 4989 <listitem> 4990 <para> 4991 yellow 4992 </para> 4993 </listitem> 4994 <listitem> 4995 <para> 4996 red 4997 </para> 4998 </listitem> 4999 <listitem> 5000 <para> 5001 default 5002 </para> 5003 </listitem> 5004 </itemizedlist> 5005 <para> 5006 In addition to the colors, objects may have their <emphasis>attributes</emphasis> set: 5007 </para> 5008 <itemizedlist> 5009 <listitem> 5010 <para>none</para> 5011 </listitem> 5012 <listitem> 5013 <para>bold</para> 5014 </listitem> 5015 <listitem> 5016 <para>reverse</para> 5017 </listitem> 5018 <listitem> 5019 <para>standout</para> 5020 </listitem> 5021 <listitem> 5022 <para>underline</para> 5023 </listitem> 5024 </itemizedlist> 5025 <para> 5026 If your terminal supports it, the special keyword 5027 <emphasis>default</emphasis> can be used as a transparent color. The 5028 value <emphasis>brightdefault</emphasis> is also valid. If NeoMutt is 5029 linked against the <emphasis>S-Lang</emphasis> library, you also need 5030 to set the <literal>$COLORFGBG</literal> environment variable to the 5031 default colors of your terminal for this to work; for example (for 5032 Bourne-like shells): 5033 </para> 5034<screen> 5035set COLORFGBG="green;black" 5036export COLORFGBG 5037</screen> 5038 <note> 5039 <para> 5040 The <emphasis>S-Lang</emphasis> library requires you to use the 5041 <emphasis>lightgray</emphasis> and <emphasis>brown</emphasis> 5042 keywords instead of <emphasis>white</emphasis> and 5043 <emphasis>yellow</emphasis> when setting this variable. 5044 </para> 5045 </note> 5046 </sect2> 5047 5048 <sect2 id="color-simple"> 5049 <title>Simple Colors</title> 5050 <para> 5051 Most of NeoMutt's colorable objects follow simple rules. 5052 They don't use a pattern and any new configuration will overwrite the 5053 old colours. 5054 </para> 5055 <para> 5056 Simple colors can be undone by setting the foreground and background 5057 to <literal>default</literal>, or by using the <literal>uncolor</literal> 5058 command. 5059 </para> 5060 <para> 5061 These are general NeoMutt objects: 5062 </para> 5063 <table id="table-color-simple"> 5064 <title>Simple Colours</title> 5065 <tgroup cols="2"> 5066 <thead> 5067 <row> 5068 <entry>Colour Name</entry> 5069 <entry>Description</entry> 5070 </row> 5071 </thead> 5072 <tbody> 5073 <row> 5074 <entry>attachment</entry> 5075 <entry>Colour for attachment headers</entry> 5076 </row> 5077 <row> 5078 <entry>bold</entry> 5079 <entry>Highlighting bold patterns in the body of messages</entry> 5080 </row> 5081 <row> 5082 <entry>error</entry> 5083 <entry>Error messages printed by NeoMutt</entry> 5084 </row> 5085 <row> 5086 <entry>hdrdefault</entry> 5087 <entry>Default colour of the message header in the pager</entry> 5088 </row> 5089 <row> 5090 <entry>indicator</entry> 5091 <entry>Arrow or bar used to indicate the current item in a menu</entry> 5092 </row> 5093 <row> 5094 <entry>markers</entry> 5095 <entry>The "+" markers at the beginning of wrapped lines in the pager</entry> 5096 </row> 5097 <row> 5098 <entry>message</entry> 5099 <entry>Informational messages</entry> 5100 </row> 5101 <row> 5102 <entry>normal</entry> 5103 <entry>Default colour for all text</entry> 5104 </row> 5105 <row> 5106 <entry>options</entry> 5107 <entry>The key letters in multi-choice questions</entry> 5108 </row> 5109 <row> 5110 <entry>progress</entry> 5111 <entry><link linkend="progress">Visual progress bar</link></entry> 5112 </row> 5113 <row> 5114 <entry>prompt</entry> 5115 <entry>A question</entry> 5116 </row> 5117 <row> 5118 <entry>search</entry> 5119 <entry>Highlighting of words in the pager</entry> 5120 </row> 5121 <row> 5122 <entry>signature</entry> 5123 <entry>Email's signature lines (.sig)</entry> 5124 </row> 5125 <row> 5126 <entry>tilde</entry> 5127 <entry>The "~" used to pad blank lines in the pager</entry> 5128 </row> 5129 <row> 5130 <entry>tree</entry> 5131 <entry>Thread tree drawn in the message index and attachment menu</entry> 5132 </row> 5133 <row> 5134 <entry>underline</entry> 5135 <entry>Highlighting underlined patterns in the body of messages</entry> 5136 </row> 5137 <row> 5138 <entry>warning</entry> 5139 <entry>Warning messages</entry> 5140 </row> 5141 </tbody> 5142 </tgroup> 5143 </table> 5144<screen> 5145<emphasis role="comment"># Make error messages white text on a red background</emphasis> 5146color error white red 5147<emphasis role="comment"># Make questions bold, underlined, with light blue text (with default background)</emphasis> 5148color prompt bold underline cyan default 5149</screen> 5150<screen> 5151uncolor error 5152uncolor prompt 5153</screen> 5154 <para> 5155 Each of these objects will colour a certain expando in the index. 5156 See <link linkend="index-format">$index_format</link> for more details. 5157 </para> 5158 <table id="color-simple-index"> 5159 <title>Simple Index Colours</title> 5160 <tgroup cols="2"> 5161 <thead> 5162 <row> 5163 <entry>Colour Name</entry> 5164 <entry>Description</entry> 5165 </row> 5166 </thead> 5167 <tbody> 5168 <row> 5169 <entry>index_collapsed</entry> 5170 <entry>Number of messages in a collapsed thread, <literal>%M</literal></entry> 5171 </row> 5172 <row> 5173 <entry>index_date</entry> 5174 <entry>Date field, <literal>%d</literal> <literal>%D</literal> <literal>%{fmt}</literal> <literal>%[fmt]</literal> <literal>%(fmt)</literal></entry> 5175 </row> 5176 <row> 5177 <entry>index_label</entry> 5178 <entry>Message label, <literal>%y</literal> <literal>%Y</literal></entry> 5179 </row> 5180 <row> 5181 <entry>index_number</entry> 5182 <entry>Message number, <literal>%C</literal></entry> 5183 </row> 5184 <row> 5185 <entry>index_size</entry> 5186 <entry>Message size, <literal>%c</literal> <literal>%cr</literal> <literal>%l</literal></entry> 5187 </row> 5188 <row> 5189 <entry>index_tags</entry> 5190 <entry>Transformed message tags, <literal>%g</literal> <literal>%J</literal></entry> 5191 </row> 5192 </tbody> 5193 </tgroup> 5194 </table> 5195<screen> 5196color index_date green default 5197</screen> 5198<screen> 5199uncolor index_date 5200</screen> 5201 <para> 5202 These are sidebar objects. 5203 See <link linkend="sidebar-intro">Sidebar Intro</link> for more details. 5204 </para> 5205 <table id="color-simple-sidebar"> 5206 <title>Simple Sidebar Colours</title> 5207 <tgroup cols="2"> 5208 <thead> 5209 <row> 5210 <entry>Colour Name</entry> 5211 <entry>Description</entry> 5212 </row> 5213 </thead> 5214 <tbody> 5215 <row> 5216 <entry>sidebar_divider</entry> 5217 <entry>The dividing line between the Sidebar and the Index/Pager panels</entry> 5218 </row> 5219 <row> 5220 <entry>sidebar_flagged</entry> 5221 <entry>Mailboxes containing flagged mail</entry> 5222 </row> 5223 <row> 5224 <entry>sidebar_highlight</entry> 5225 <entry>Cursor to select a mailbox</entry> 5226 </row> 5227 <row> 5228 <entry>sidebar_indicator</entry> 5229 <entry>The mailbox open in the Index panel</entry> 5230 </row> 5231 <row> 5232 <entry>sidebar_new</entry> 5233 <entry>Mailboxes containing new mail</entry> 5234 </row> 5235 <row> 5236 <entry>sidebar_ordinary</entry> 5237 <entry>Mailboxes that have no new/flagged mails, etc</entry> 5238 </row> 5239 <row> 5240 <entry>sidebar_spool_file</entry> 5241 <entry>Mailbox that receives incoming mail</entry> 5242 </row> 5243 <row> 5244 <entry>sidebar_unread</entry> 5245 <entry>Mailboxes containing unread mail</entry> 5246 </row> 5247 </tbody> 5248 </tgroup> 5249 </table> 5250<screen> 5251color sidebar_divider brightblack default 5252</screen> 5253<screen> 5254uncolor sidebar_divider 5255</screen> 5256 <para> 5257 These are compose objects. 5258 </para> 5259 <note> 5260 <para> 5261 The compose objects use a slightly different format of command. 5262 They prefix the style with the word <literal>compose</literal>. 5263 </para> 5264 </note> 5265 <table id="color-simple-compose"> 5266 <title>Simple Compose Colours</title> 5267 <tgroup cols="2"> 5268 <thead> 5269 <row> 5270 <entry>Colour Name</entry> 5271 <entry>Description</entry> 5272 </row> 5273 </thead> 5274 <tbody> 5275 <row> 5276 <entry>header</entry> 5277 <entry>Header labels, e.g. From:</entry> 5278 </row> 5279 <row> 5280 <entry>security_encrypt</entry> 5281 <entry>Mail will be encrypted</entry> 5282 </row> 5283 <row> 5284 <entry>security_sign</entry> 5285 <entry>Mail will be signed</entry> 5286 </row> 5287 <row> 5288 <entry>security_both</entry> 5289 <entry>Mail will be encrypted and signed</entry> 5290 </row> 5291 <row> 5292 <entry>security_none</entry> 5293 <entry>Mail will not be encrypted or signed</entry> 5294 </row> 5295 </tbody> 5296 </tgroup> 5297 </table> 5298<screen> 5299color compose header bold white default 5300</screen> 5301<screen> 5302uncolor compose header 5303</screen> 5304 <para> 5305 The quoted objects refer to quoted lines in an email reply. 5306 They are defined using the 5307 <link linkend="reply-regex"><literal>$reply_regex</literal></link> 5308 config variable. 5309 </para> 5310 <para> 5311 The quoted email colours don't use pattern. 5312 The first colour, <literal>quoted</literal> provides a default colour 5313 for all quoted text. Also, each diffent level of quoting can be given 5314 a different colour using, <literal>quoted1</literal>, 5315 <literal>quoted2</literal>, <literal>quoted3</literal> up to 5316 <literal>quoted9</literal>. 5317 </para> 5318 <table id="color-quoted"> 5319 <title>Quoted Email Colours</title> 5320 <tgroup cols="2"> 5321 <thead> 5322 <row> 5323 <entry>Colour Name</entry> 5324 <entry>Description</entry> 5325 </row> 5326 </thead> 5327 <tbody> 5328 <row> 5329 <entry>quoted</entry> 5330 <entry>Text matching <link linkend="quote-regex">$quote_regex</link> in the body of a message</entry> 5331 </row> 5332 <row> 5333 <entry>quoted1</entry> 5334 <entry>1 level deeper quoted text, e.g. <literal>> > text</literal></entry> 5335 </row> 5336 <row> 5337 <entry>quoted2</entry> 5338 <entry>2 level deeper quoted text, e.g. <literal>> > > text</literal></entry> 5339 </row> 5340 <row> 5341 <entry>...</entry> 5342 <entry>...</entry> 5343 </row> 5344 <row> 5345 <entry>quoted9</entry> 5346 <entry>9 level deeper quoted text</entry> 5347 </row> 5348 </tbody> 5349 </tgroup> 5350 </table> 5351<screen> 5352color quoted brightblue default 5353color quoted1 brightgreen default 5354color quoted2 yellow default 5355</screen> 5356<screen> 5357uncolor quoted 5358uncolor quoted1 5359uncolor quoted2 5360</screen> 5361 </sect2> 5362 5363 <sect2 id="color-lists"> 5364 <title>Color Lists</title> 5365 <para> 5366 Some objects in NeoMutt support <emphasis>lists</emphasis> of color 5367 rules. Each rule has a pattern and a color. 5368 Each is checked in turn 5369 and any matching rules are applied cumulatively (overlaid). 5370 </para> 5371 <para> 5372 When applying the colours, each pattern will be tested against the 5373 field to be colored. All of the matching patterns will have their 5374 colors applied in the order they are configured. 5375 </para> 5376 <para> 5377 The color lists work in slightly different ways to each other. 5378 </para> 5379 <para> 5380 <literal>attach_headers</literal>, <literal>body</literal> and 5381 <literal>header</literal> match a <emphasis>regular expression</emphasis> 5382 (regex) in the header/body of a email. 5383 </para> 5384 <para> 5385 <literal>index</literal> objects match a <emphasis>pattern</emphasis> 5386 in the email index (see <xref linkend="patterns" />) 5387 Note that IMAP server-side searches (=b, =B, =h) are not 5388 supported for color index patterns. 5389 </para> 5390 <para> 5391 When <link linkend="header-color-partial">$header_color_partial</link> 5392 is unset (the default), a <literal>header</literal> matched by 5393 <emphasis>regex</emphasis> will have color applied to the entire 5394 header. When set, color is applied only to the exact text matched by 5395 <emphasis>regex</emphasis>. 5396 </para> 5397 <para> 5398 For the <literal>status</literal> list, the 5399 <emphasis>regular expression</emphasis> is optional. Without one, 5400 the command will set the default style for the status bar. With a 5401 regex (and an optional number), it's possible to style parts of the 5402 status bar. See: <link linkend="status-color">Status-Color feature</link> 5403 for more detail. 5404 </para> 5405 <para> 5406 Color lists can be undone by using the <literal>uncolor</literal> 5407 command and the pattern or <literal>*</literal> to match. 5408 </para> 5409 <table id="color-regex-lists"> 5410 <title>Colour Regex Lists</title> 5411 <tgroup cols="3"> 5412 <thead> 5413 <row> 5414 <entry>Colour Name</entry> 5415 <entry>Match</entry> 5416 <entry>Description</entry> 5417 </row> 5418 </thead> 5419 <tbody> 5420 <row> 5421 <entry>attach_headers</entry> 5422 <entry>regex</entry> 5423 <entry>Attachment headers</entry> 5424 </row> 5425 <row> 5426 <entry>body</entry> 5427 <entry>regex</entry> 5428 <entry>Email body</entry> 5429 </row> 5430 <row> 5431 <entry>header</entry> 5432 <entry>regex</entry> 5433 <entry>Email headers</entry> 5434 </row> 5435 <row> 5436 <entry>index</entry> 5437 <entry>pattern</entry> 5438 <entry>Default highlighting of the entire index line</entry> 5439 </row> 5440 <row> 5441 <entry>index_author</entry> 5442 <entry>pattern</entry> 5443 <entry>Author in the index, %A %a %F %L %n</entry> 5444 </row> 5445 <row> 5446 <entry>index_flags</entry> 5447 <entry>pattern</entry> 5448 <entry>Flags in the index, %S %Z</entry> 5449 </row> 5450 <row> 5451 <entry>index_subject</entry> 5452 <entry>pattern</entry> 5453 <entry>Subject in the index, %s</entry> 5454 </row> 5455 <row> 5456 <entry>index_tag</entry> 5457 <entry>pattern</entry> 5458 <entry>Tags in the index, %G</entry> 5459 </row> 5460 <row> 5461 <entry>status</entry> 5462 <entry>regex</entry> 5463 <entry>Status bar</entry> 5464 </row> 5465 </tbody> 5466 </tgroup> 5467 </table> 5468<screen> 5469<emphasis role="comment"># Highlight emails from work (entire line)</emphasis> 5470color index cyan default "~f @work.com" 5471<emphasis role="comment"># Extra highlighting for the boss (just the author column)</emphasis> 5472color index_author cyan red "~f boss@work.com" 5473</screen> 5474<screen> 5475uncolor index "~f @work.com" 5476<emphasis role="comment"># Clear all index_author colors</emphasis> 5477uncolor index_author * 5478</screen> 5479<screen> 5480<emphasis role="comment"># Add some highlights to the body of an email</emphasis> 5481color body bold red default "(urgent|important)" 5482color body yellow default "(warning|notice)" 5483<emphasis role="comment"># Make the label header red</emphasis> 5484color header cyan default "X-Label" 5485</screen> 5486<screen> 5487uncolor body "(urgent|important)" 5488<emphasis role="comment"># Clear all body colors</emphasis> 5489uncolor body * 5490uncolor header "X-Label" 5491</screen> 5492<screen> 5493<emphasis role="comment"># Set the default color for the entire status line</emphasis> 5494color status blue white 5495<emphasis role="comment"># Highlight New, Deleted, or Flagged emails</emphasis> 5496color status brightred white '(New|Del|Flag):[0-9]+' 5497<emphasis role="comment"># Highlight the contents of the []s but not the [] themselves</emphasis> 5498color status red default '\[([^]]+)\]' 1 5499</screen> 5500<screen> 5501uncolor status '(New|Del|Flag):[0-9]+' 5502uncolor status * 5503</screen> 5504 </sect2> 5505 5506 <sect2 id="color-mono"> 5507 <title>Mono Color</title> 5508 5509 <para> 5510 If your terminal does not support color, it is still possible change 5511 the video attributes through the use of the <quote>mono</quote> 5512 command. Usage: 5513 </para> 5514 <cmdsynopsis> 5515 <command>mono</command> 5516 <arg choice="plain"> 5517 <replaceable class="parameter">object</replaceable> 5518 </arg> 5519 <arg choice="plain"> 5520 <replaceable class="parameter">attribute</replaceable> 5521 </arg> 5522 <command>mono</command> 5523 <group choice="req"> 5524 <arg choice="plain"> 5525 <option>header</option> 5526 </arg> 5527 <arg choice="plain"> 5528 <option>body</option> 5529 </arg> 5530 </group> 5531 <arg choice="plain"> 5532 <replaceable class="parameter">attribute</replaceable> 5533 </arg> 5534 <arg choice="plain"> 5535 <replaceable class="parameter">regex</replaceable> 5536 </arg> 5537 <command>mono</command> 5538 <arg choice="plain"> 5539 <option>index-object</option> 5540 </arg> 5541 <arg choice="plain"> 5542 <replaceable class="parameter">attribute</replaceable> 5543 </arg> 5544 <arg choice="plain"> 5545 <replaceable class="parameter">pattern</replaceable> 5546 </arg> 5547 <command>unmono</command> 5548 <group choice="req"> 5549 <arg choice="plain"> 5550 <option>index-object</option> 5551 </arg> 5552 <arg choice="plain"> 5553 <option>header</option> 5554 </arg> 5555 <arg choice="plain"> 5556 <option>body</option> 5557 </arg> 5558 </group> 5559 <group choice="req"> 5560 <arg choice="plain"> 5561 <replaceable>*</replaceable> 5562 </arg> 5563 <arg choice="plain" rep="repeat"> 5564 <replaceable>pattern</replaceable> 5565 </arg> 5566 </group> 5567 </cmdsynopsis> 5568 <para> 5569 For <emphasis>object</emphasis>, <emphasis>composeobject</emphasis>, and 5570 <emphasis>attribute</emphasis>, see the <command>color</command> command. 5571 </para> 5572 </sect2> 5573 </sect1> 5574 5575 <sect1 id="msg-hdr-display"> 5576 <title>Message Header Display</title> 5577 5578 <sect2 id="hdr-folding"> 5579 <title>Header Display</title> 5580 <para> 5581 When displaying a message in the pager, NeoMutt folds long header 5582 lines at <link linkend="wrap">$wrap</link> columns. Though there're 5583 precise rules about where to break and how, NeoMutt always folds 5584 headers using a tab for readability. (Note that the sending side is 5585 not affected by this, NeoMutt tries to implement standards compliant 5586 folding.) 5587 </para> 5588 <para> 5589 Despite not being a real header, NeoMutt will also display an mbox 5590 "From_" line in the pager along with other headers. This 5591 line can be manipulated with <command>ignore/unignore</command> and 5592 <command>hdr_order/unhdr_order</command> commands. 5593 </para> 5594 </sect2> 5595 5596 <sect2 id="ignore"> 5597 <title>Selecting Headers</title> 5598 <para> 5599 Usage: 5600 </para> 5601 <cmdsynopsis> 5602 <command>ignore</command> 5603 <arg choice="plain"> 5604 <replaceable class="parameter">pattern</replaceable> 5605 </arg> 5606 <arg choice="opt" rep="repeat"> 5607 <replaceable class="parameter">pattern</replaceable> 5608 </arg> 5609 <command>unignore</command> 5610 <group choice="req"> 5611 <arg choice="plain"> 5612 <replaceable>*</replaceable> 5613 </arg> 5614 <arg choice="plain" rep="repeat"> 5615 <replaceable>pattern</replaceable> 5616 </arg> 5617 </group> 5618 </cmdsynopsis> 5619 <para> 5620 Messages often have many header fields added by automatic processing 5621 systems, or which may not seem useful to display on the screen. This 5622 command allows you to specify header fields which you don't normally 5623 want to see in the pager. 5624 </para> 5625 <para> 5626 You do not need to specify the full header field name. For example, 5627 <quote>ignore content-</quote> will ignore all header fields that 5628 begin with the pattern <quote>content-</quote>. 5629 <quote>ignore *</quote> will ignore all headers. 5630 </para> 5631 <para> 5632 To remove a previously added token from the list, use the 5633 <quote>unignore</quote> command. The <quote>unignore</quote> command 5634 will make NeoMutt display headers with the given pattern. For 5635 example, if you do <quote>ignore x-</quote> it is possible to 5636 <quote>unignore x-mailer</quote>. 5637 </para> 5638 <para> 5639 <quote>unignore *</quote> will remove all tokens from the ignore 5640 list. 5641 </para> 5642 <example id="ex-header-weeding"> 5643 <title>Header weeding</title> 5644 5645<screen> 5646<emphasis role="comment"># Sven's draconian header weeding</emphasis> 5647ignore * 5648unignore from date subject to cc 5649unignore organization organisation x-mailer: x-newsreader: x-mailing-list: 5650unignore posted-to: 5651</screen> 5652 5653 </example> 5654 <para> 5655 The above example will show "From:" headers as well as mbox 5656 "From_" lines. To hide the latter, instead use 5657 "<literal>unignore from: date subject to cc</literal>" on 5658 the second line. 5659 </para> 5660 </sect2> 5661 5662 <sect2 id="hdr-order"> 5663 <title>Ordering Displayed Headers</title> 5664 <para> 5665 Usage: 5666 </para> 5667 <cmdsynopsis> 5668 <command>hdr_order</command> 5669 <arg choice="plain"> 5670 <replaceable class="parameter">header</replaceable> 5671 </arg> 5672 <arg choice="opt" rep="repeat"> 5673 <replaceable class="parameter">header</replaceable> 5674 </arg> 5675 <command>unhdr_order</command> 5676 <group choice="req"> 5677 <arg choice="plain"> 5678 <replaceable>*</replaceable> 5679 </arg> 5680 <arg choice="plain" rep="repeat"> 5681 <replaceable>header</replaceable> 5682 </arg> 5683 </group> 5684 </cmdsynopsis> 5685 <para> 5686 With the <command>hdr_order</command> command you can specify an 5687 order in which NeoMutt will attempt to present these headers to you 5688 when viewing messages. 5689 </para> 5690 <para> 5691 <quote><command>unhdr_order</command>*</quote> will clear all 5692 previous headers from the order list, thus removing the header order 5693 effects set by the system-wide startup file. 5694 </para> 5695 <example id="ex-hdr-order"> 5696 <title>Configuring header display order</title> 5697 <screen>hdr_order From Date: From: To: Cc: Subject:</screen> 5698 </example> 5699 </sect2> 5700 </sect1> 5701 5702 <sect1 id="alternates"> 5703 <title>Alternative Addresses</title> 5704 <para> 5705 Usage: 5706 </para> 5707 <cmdsynopsis> 5708 <command>alternates</command> 5709 <arg choice="opt" rep="repeat"> 5710 <option>-group</option> 5711 <replaceable>name</replaceable> 5712 </arg> 5713 <arg choice="plain"> 5714 <replaceable>regex</replaceable> 5715 </arg> 5716 <arg choice="opt" rep="repeat"> 5717 <replaceable>regex</replaceable> 5718 </arg> 5719 <command>unalternates</command> 5720 <arg choice="opt" rep="repeat"> 5721 <option>-group</option> 5722 <replaceable>name</replaceable> 5723 </arg> 5724 <group choice="req"> 5725 <arg choice="plain"> 5726 <replaceable>*</replaceable> 5727 </arg> 5728 <arg choice="plain" rep="repeat"> 5729 <replaceable>regex</replaceable> 5730 </arg> 5731 </group> 5732 </cmdsynopsis> 5733 <para> 5734 With various functions, NeoMutt will treat messages differently, 5735 depending on whether you sent them or whether you received them from 5736 someone else. For instance, when replying to a message that you sent to 5737 a different party, NeoMutt will automatically suggest to send the 5738 response to the original message's recipients – responding to yourself 5739 won't make much sense in many cases. (See 5740 <link linkend="reply-to">$reply_to</link>.) 5741 </para> 5742 <para> 5743 Many users receive e-mail under a number of different addresses. To 5744 fully use NeoMutt's features here, the program must be able to 5745 recognize what e-mail addresses you receive mail under. That's the 5746 purpose of the <command>alternates</command> command: It takes a list 5747 of regular expressions, each of which can identify an address under 5748 which you receive e-mail. 5749 </para> 5750 <para> 5751 As addresses are matched using regular expressions and not exact strict 5752 comparisons, you should make sure you specify your addresses as precise 5753 as possible to avoid mismatches. For example, if you specify: 5754 </para> 5755 <screen>alternates user@example</screen> 5756 <para> 5757 NeoMutt will consider 5758 <quote><literal>some-user@example</literal></quote> as being your 5759 address, too which may not be desired. As a solution, in such cases 5760 addresses should be specified as: 5761 </para> 5762 <screen>alternates '^user@example$'</screen> 5763 <para> 5764 The <literal>-group</literal> flag causes all of the subsequent regular 5765 expressions to be added to the named group. 5766 </para> 5767 <para> 5768 The <command>unalternates</command> command can be used to write 5769 exceptions to <command>alternates</command> patterns. If an address 5770 matches something in an <command>alternates</command> command, but you 5771 nonetheless do not think it is from you, you can list a more precise 5772 pattern under an <command>unalternates</command> command. 5773 </para> 5774 <para> 5775 To remove a regular expression from the <command>alternates</command> 5776 list, use the <command>unalternates</command> command with exactly the 5777 same <emphasis>regex</emphasis>. Likewise, if the 5778 <emphasis>regex</emphasis> for an <command>alternates</command> command 5779 matches an entry on the <command>unalternates</command> list, that 5780 <command>unalternates</command> entry will be removed. If the 5781 <emphasis>regex</emphasis> for <command>unalternates</command> is 5782 <quote>*</quote>, <emphasis>all entries</emphasis> on 5783 <command>alternates</command> will be removed. 5784 </para> 5785 </sect1> 5786 5787 <sect1 id="lists"> 5788 <title>Mailing Lists</title> 5789 <anchor id="subscribe" /> 5790 <para> 5791 Usage: 5792 </para> 5793 <cmdsynopsis> 5794 <command>lists</command> 5795 <arg choice="opt" rep="repeat"> 5796 <option>-group</option> 5797 <replaceable class="parameter">name</replaceable> 5798 </arg> 5799 <arg choice="plain"> 5800 <replaceable class="parameter">regex</replaceable> 5801 </arg> 5802 <arg choice="opt" rep="repeat"> 5803 <replaceable class="parameter">regex</replaceable> 5804 </arg> 5805 <command>unlists</command> 5806 <group choice="req"> 5807 <arg choice="plain"> 5808 <replaceable class="parameter">*</replaceable> 5809 </arg> 5810 <arg choice="plain" rep="repeat"> 5811 <replaceable class="parameter">regex</replaceable> 5812 </arg> 5813 </group> 5814 <command>subscribe</command> 5815 <arg choice="opt" rep="repeat"> 5816 <option>-group</option> 5817 <replaceable class="parameter">name</replaceable> 5818 </arg> 5819 <arg choice="plain"> 5820 <replaceable class="parameter">regex</replaceable> 5821 </arg> 5822 <arg choice="opt" rep="repeat"> 5823 <replaceable class="parameter">regex</replaceable> 5824 </arg> 5825 <command>unsubscribe</command> 5826 <group choice="req"> 5827 <arg choice="plain"> 5828 <replaceable class="parameter">*</replaceable> 5829 </arg> 5830 <arg choice="plain" rep="repeat"> 5831 <replaceable class="parameter">regex</replaceable> 5832 </arg> 5833 </group> 5834 </cmdsynopsis> 5835 <para> 5836 NeoMutt has a few nice features for 5837 <link linkend="using-lists">handling mailing lists</link>. In order to 5838 take advantage of them, you must specify which addresses belong to 5839 mailing lists, and which mailing lists you are subscribed to. NeoMutt 5840 also has limited support for auto-detecting mailing lists: it supports 5841 parsing <literal>mailto:</literal> links in the common 5842 <literal>List-Post:</literal> header which has the same effect as 5843 specifying the list address via the <command>lists</command> command 5844 (except the group feature). Once you have done this, the 5845 <link linkend="list-reply"><literal><list-reply></literal></link> 5846 function will work for all known lists. Additionally, when you send a 5847 message to a known list and <link linkend="followup-to">$followup_to</link> 5848 is set, NeoMutt will add a Mail-Followup-To header. For unsubscribed 5849 lists, this will include your personal address, ensuring you receive a 5850 copy of replies. For subscribed mailing lists, the header will not, 5851 telling other users' mail user agents not to send copies of replies to 5852 your personal address. 5853 </para> 5854 <note> 5855 <para> 5856 The Mail-Followup-To header is a non-standard extension which is not 5857 supported by all mail user agents. Adding it is not bullet-proof 5858 against receiving personal CCs of list messages. Also note that the 5859 generation of the Mail-Followup-To header is controlled by the 5860 <link linkend="followup-to">$followup_to</link> configuration 5861 variable since it's common practice on some mailing lists to send Cc 5862 upon replies (which is more a group- than a list-reply). 5863 </para> 5864 </note> 5865 <para> 5866 More precisely, NeoMutt maintains lists of patterns for the addresses 5867 of known and subscribed mailing lists. Every subscribed mailing list is 5868 known. To mark a mailing list as known, use the <command>list</command> 5869 command. To mark it as subscribed, use <command>subscribe</command>. 5870 </para> 5871 <para> 5872 You can use regular expressions with both commands. To mark all 5873 messages sent to a specific bug report's address on Debian's bug 5874 tracking system as list mail, for instance, you could say 5875 </para> 5876 <screen>subscribe [0-9]+.*@bugs.debian.org</screen> 5877 <para> 5878 as it's often sufficient to just give a portion of the list's e-mail 5879 address. 5880 </para> 5881 <para> 5882 Specify as much of the address as you need to to remove ambiguity. For 5883 example, if you've subscribed to the NeoMutt mailing list, you will 5884 receive mail addressed to <literal>neomutt-users@neomutt.org</literal>. 5885 So, to tell NeoMutt that this is a mailing list, you could add 5886 <literal>lists neomutt-users@</literal> to your initialization file. To 5887 tell NeoMutt that you are subscribed to it, add 5888 <literal><command>subscribe</command> neomutt-users</literal> to your 5889 initialization file instead. If you also happen to get mail from 5890 someone whose address is <literal>neomutt-users@example.com</literal>, 5891 you could use 5892 <literal><command>lists</command> ^neomutt-users@neomutt\\.org$</literal> 5893 or 5894 <literal><command>subscribe</command> ^neomutt-users@neomutt\\.org$</literal> 5895 to match only mail from the actual list. 5896 </para> 5897 <para> 5898 The <literal>-group</literal> flag adds all of the subsequent regular 5899 expressions to the named <link linkend="addrgroup">address group</link> 5900 in addition to adding to the specified address list. 5901 </para> 5902 <para> 5903 The <quote>unlists</quote> command is used to remove a token from the 5904 list of known and subscribed mailing-lists. Use 5905 <quote>unlists *</quote> to remove all tokens. 5906 </para> 5907 <para> 5908 To remove a mailing list from the list of subscribed mailing lists, but 5909 keep it on the list of known mailing lists, use 5910 <command>unsubscribe</command>. 5911 </para> 5912 </sect1> 5913 5914 <sect1 id="mbox-hook"> 5915 <title>Using Multiple Spool Mailboxes</title> 5916 <para> 5917 Usage: 5918 </para> 5919 <cmdsynopsis> 5920 <command>mbox-hook</command> 5921 <arg choice="opt"> 5922 <replaceable class="parameter">-noregex</replaceable> 5923 </arg> 5924 <arg choice="plain"> 5925 <replaceable class="parameter">pattern</replaceable> 5926 </arg> 5927 <arg choice="plain"> 5928 <replaceable class="parameter">mailbox</replaceable> 5929 </arg> 5930 </cmdsynopsis> 5931 <para> 5932 This command is used to move read messages from a specified mailbox to 5933 a different mailbox automatically when you quit or change folders. 5934 <emphasis>pattern</emphasis> is used to specifying the mailbox to 5935 treat as a <quote>spool</quote> mailbox and <emphasis>mailbox</emphasis> 5936 specifies where mail should be saved when read. 5937 The <emphasis>-noregex</emphasis> switch controls whether 5938 <emphasis>pattern</emphasis> is matched using a simple string 5939 comparison or a full regex match. 5940 </para> 5941 <para> 5942 The regex parameter has 5943 <link linkend="shortcuts">mailbox shortcut</link> expansion performed 5944 on the first character. See <xref linkend="mailbox-hook" /> for more 5945 details. 5946 </para> 5947 <para> 5948 Note that execution of mbox-hooks is dependent on the 5949 <link linkend="move">$move</link> configuration variable. If set to 5950 <quote>no</quote> (the default), mbox-hooks will not be executed. 5951 </para> 5952 <para> 5953 Unlike some of the other <emphasis>hook</emphasis> commands, only the 5954 <emphasis>first</emphasis> matching regex is used (it is not possible 5955 to save read mail in more than a single mailbox). 5956 </para> 5957 </sect1> 5958 5959 <sect1 id="mailboxes"> 5960 <title>Monitoring Incoming Mail</title> 5961 <para> 5962 Usage: 5963 </para> 5964 <cmdsynopsis> 5965 <command>mailboxes</command> 5966 <arg choice="plain"> 5967 <replaceable class="parameter">mailbox</replaceable> 5968 </arg> 5969 <arg choice="opt" rep="repeat"> 5970 <replaceable class="parameter">mailbox</replaceable> 5971 </arg> 5972 <command>named-mailboxes</command> 5973 <arg choice="plain"> 5974 <replaceable class="parameter">description</replaceable> 5975 <arg choice="plain"> 5976 <replaceable class="parameter">mailbox</replaceable> 5977 </arg> 5978 </arg> 5979 <group choice="req" rep="repeat"> 5980 <arg choice="plain"> 5981 <replaceable class="parameter">description</replaceable> 5982 <arg choice="plain"> 5983 <replaceable class="parameter">mailbox</replaceable> 5984 </arg> 5985 </arg> 5986 </group> 5987 <command>unmailboxes</command> 5988 <group choice="req"> 5989 <arg choice="plain"> 5990 <replaceable class="parameter">*</replaceable> 5991 </arg> 5992 <arg choice="plain" rep="repeat"> 5993 <replaceable class="parameter">mailbox</replaceable> 5994 </arg> 5995 </group> 5996 </cmdsynopsis> 5997 <para> 5998 This command specifies folders which can receive mail and which will be 5999 checked for new messages periodically. 6000 </para> 6001 <para> 6002 <emphasis>folder</emphasis> can either be a local file or directory 6003 (Mbox/Mmdf or Maildir/Mh). If NeoMutt was built with POP and/or IMAP 6004 support, <emphasis>folder</emphasis> can also be a POP/IMAP folder URL. 6005 The URL syntax is described in <xref linkend="url-syntax" />, POP and 6006 IMAP are described in <xref linkend="pop" /> and 6007 <xref linkend="imap" /> respectively. 6008 </para> 6009 <para> 6010 NeoMutt provides a number of advanced features for handling (possibly 6011 many) folders and new mail within them, please refer to 6012 <xref linkend="new-mail" /> for details (including in what situations 6013 and how often NeoMutt checks for new mail). Additionally, 6014 <link linkend="new-mail-command">$new_mail_command</link> can be used 6015 to run a command when new mail is detected. 6016 </para> 6017 <para> 6018 The <quote>unmailboxes</quote> command is used to remove a token from 6019 the list of folders which receive mail. <quote>unmailboxes</quote> can 6020 be used on the mailbox path, <quote>$folder</quote>-abbreviated path, 6021 or description. Use <quote>unmailboxes *</quote> to remove all 6022 tokens. 6023 </para> 6024 <note> 6025 <para> 6026 The folders in the <command>mailboxes</command> command are resolved 6027 when the command is executed, so if these names contain 6028 <link linkend="shortcuts">shortcut characters</link> (such as 6029 <quote>=</quote> and <quote>!</quote>), any variable definition that 6030 affects these characters (like <link linkend="folder">$folder</link> 6031 and <link linkend="spool-file">$spool_file</link>) should be set before 6032 the <command>mailboxes</command> command. If none of these shortcuts 6033 are used, a local path should be absolute as otherwise NeoMutt tries 6034 to find it relative to the directory from where NeoMutt was started 6035 which may not always be desired. 6036 </para> 6037 </note> 6038 </sect1> 6039 6040 <sect1 id="my-hdr"> 6041 <title>User-Defined Headers</title> 6042 <para> 6043 Usage: 6044 </para> 6045 <cmdsynopsis> 6046 <command>my_hdr</command> 6047 <arg choice="plain"> 6048 <replaceable class="parameter">string</replaceable> 6049 </arg> 6050 <command>unmy_hdr</command> 6051 <group choice="req"> 6052 <arg choice="plain"> 6053 <replaceable class="parameter">*</replaceable> 6054 </arg> 6055 <arg choice="plain" rep="repeat"> 6056 <replaceable class="parameter">field</replaceable> 6057 </arg> 6058 </group> 6059 </cmdsynopsis> 6060 <para> 6061 The <command>my_hdr</command> command allows you to create your own 6062 header fields which will be added to every message you send and appear 6063 in the editor if <link linkend="edit-headers">$edit_headers</link> is 6064 set. 6065 </para> 6066 <para> 6067 For example, if you would like to add an <quote>Organization:</quote> 6068 header field to all of your outgoing messages, you can put the command 6069 something like shown in <xref linkend="ex-my-hdr" /> in your 6070 <literal>.neomuttrc</literal>. 6071 </para> 6072 <example id="ex-my-hdr"> 6073 <title>Defining custom headers</title> 6074 6075<screen> 6076my_hdr Organization: A Really Big Company, Anytown, USA 6077</screen> 6078 6079 </example> 6080 <note> 6081 <para> 6082 Space characters are <emphasis>not</emphasis> allowed between the 6083 keyword and the colon (<quote>:</quote>). The standard for 6084 electronic mail (RFC2822) says that space is illegal there, so 6085 NeoMutt enforces the rule. 6086 </para> 6087 </note> 6088 <para> 6089 If you would like to add a header field to a single message, you should 6090 either set the <link linkend="edit-headers">$edit_headers</link> 6091 variable, or use the <literal><edit-headers></literal> function 6092 (default: <quote>E</quote>) in the compose menu so that you can edit 6093 the header of your message along with the body. 6094 </para> 6095 <para> 6096 To remove user defined header fields, use the 6097 <command>unmy_hdr</command> command. You may specify an asterisk 6098 (<quote>*</quote>) to remove all header fields, or the fields to 6099 remove. For example, to remove all <quote>To</quote> and 6100 <quote>Cc</quote> header fields, you could use: 6101 </para> 6102 <screen>unmy_hdr to cc</screen> 6103 </sect1> 6104 6105 <sect1 id="default-save-mailbox"> 6106 <title>Specify Default Fcc: and/or Save Mailbox</title> 6107 <anchor id="fcc-save-hook" /> 6108 <anchor id="fcc-hook" /> 6109 <anchor id="save-hook" /> 6110 <para> 6111 Usage: 6112 </para> 6113 <cmdsynopsis> 6114 <command>fcc-save-hook</command> 6115 <arg choice="plain"> 6116 <replaceable class="parameter">pattern</replaceable> 6117 </arg> 6118 <arg choice="plain"> 6119 <replaceable class="parameter">mailbox</replaceable> 6120 </arg> 6121 <command>fcc-hook</command> 6122 <arg choice="plain"> 6123 <replaceable class="parameter">pattern</replaceable> 6124 </arg> 6125 <arg choice="plain"> 6126 <replaceable class="parameter">mailbox</replaceable> 6127 </arg> 6128 <command>save-hook</command> 6129 <arg choice="plain"> 6130 <replaceable class="parameter">pattern</replaceable> 6131 </arg> 6132 <arg choice="plain"> 6133 <replaceable class="parameter">mailbox</replaceable> 6134 </arg> 6135 </cmdsynopsis> 6136 <para> 6137 <command>fcc-save-hook</command> is a shortcut, equivalent to doing 6138 both a <link linkend="fcc-hook"><command>fcc-hook</command></link> and 6139 a <link linkend="save-hook"><command>save-hook</command></link> with 6140 its arguments, including %-expansion on <emphasis>mailbox</emphasis> 6141 according to <link linkend="index-format">$index_format</link>. 6142 </para> 6143 <para> 6144 <command>fcc-hook</command> is used to save outgoing mail in a mailbox 6145 other than <link linkend="record">$record</link>. NeoMutt searches the 6146 initial list of message recipients for the first matching 6147 <emphasis>pattern</emphasis> and uses <emphasis>mailbox</emphasis> as 6148 the default <quote>Fcc:</quote> mailbox. If no match is found the 6149 message will be saved to <link linkend="record">$record</link> mailbox. 6150 </para> 6151 <screen>fcc-hook [@.]aol\\.com$ +spammers</screen> 6152 <para> 6153 ...will save a copy of all messages going to the aol.com domain to the 6154 <quote>+spammers</quote> mailbox by default. 6155 </para> 6156 <para> 6157 <command>save-hook</command> is used to override the default mailbox 6158 used when saving messages. <emphasis>mailbox</emphasis> will be used 6159 as the default if the message matches <emphasis>pattern</emphasis>. 6160 </para> 6161 <example id="ex-save-hook-exando"> 6162 <title>Using %-expandos in <command>save-hook</command></title> 6163 6164<screen> 6165<emphasis role="comment"># default: save all to ~/Mail/<author name></emphasis> 6166save-hook . ~/Mail/%F 6167<emphasis role="comment"># save from me@turing.cs.hmc.edu and me@cs.hmc.edu to $folder/elkins</emphasis> 6168save-hook me@(turing\\.)?cs\\.hmc\\.edu$ +elkins 6169<emphasis role="comment"># save from aol.com to $folder/spam</emphasis> 6170save-hook aol\\.com$ +spam 6171</screen> 6172 6173 </example> 6174 <para> 6175 Also see the 6176 <link linkend="fcc-save-hook"><command>fcc-save-hook</command></link> 6177 command. 6178 </para> 6179 <para> 6180 To provide more flexibility and good defaults, NeoMutt applies the 6181 expandos of <link linkend="index-format">$index_format</link> to 6182 <emphasis>mailbox</emphasis> after it was expanded. See 6183 <xref linkend="pattern-hook" /> for information on the exact format of 6184 <emphasis>pattern</emphasis>. 6185 </para> 6186 </sect1> 6187 6188 <sect1 id="send-hook"> 6189 <title>Change Settings Based Upon Message Recipients</title> 6190 <anchor id="reply-hook" /> 6191 <anchor id="send2-hook" /> 6192 <para> 6193 Usage: 6194 </para> 6195 <cmdsynopsis> 6196 <command>reply-hook</command> 6197 <arg choice="plain"> 6198 <replaceable class="parameter">pattern</replaceable> 6199 </arg> 6200 <arg choice="plain"> 6201 <replaceable class="parameter">command</replaceable> 6202 </arg> 6203 <command>send-hook</command> 6204 <arg choice="plain"> 6205 <replaceable class="parameter">pattern</replaceable> 6206 </arg> 6207 <arg choice="plain"> 6208 <replaceable class="parameter">command</replaceable> 6209 </arg> 6210 <command>send2-hook</command> 6211 <arg choice="plain"> 6212 <replaceable class="parameter">pattern</replaceable> 6213 </arg> 6214 <arg choice="plain"> 6215 <replaceable class="parameter">command</replaceable> 6216 </arg> 6217 </cmdsynopsis> 6218 <para> 6219 These commands can be used to execute arbitrary configuration commands 6220 based upon recipients of the message. <emphasis>pattern</emphasis> is 6221 used to match the message, see <xref linkend="pattern-hook" /> for 6222 details. <emphasis>command</emphasis> is executed when 6223 <emphasis>pattern</emphasis> matches. 6224 </para> 6225 <para> 6226 <command>reply-hook</command> is matched against the message you are 6227 <emphasis>replying to</emphasis>, instead of the message you are 6228 <emphasis>sending</emphasis>. <command>send-hook</command> is matched 6229 against all messages, both <emphasis>new</emphasis> and 6230 <emphasis>replies</emphasis>. 6231 </para> 6232 <note> 6233 <para> 6234 <command>reply-hook</command>s are matched 6235 <emphasis>before</emphasis> the <command>send-hook</command>, 6236 <emphasis>regardless</emphasis> of the order specified in the user's 6237 configuration file. However, you can inhibit 6238 <command>send-hook</command> in the reply case by using the pattern 6239 <literal>'! ~Q'</literal> (<emphasis>not replied</emphasis>, see 6240 <xref linkend="pattern-hook" />) in the <command>send-hook</command> 6241 to tell when <command>reply-hook</command> have been executed. 6242 </para> 6243 </note> 6244 <para> 6245 <command>send2-hook</command> is matched every time a message is 6246 changed, either by editing it, or by using the compose menu to change 6247 its recipients or subject. <command>send2-hook</command> is executed 6248 after <command>send-hook</command>, and can, e.g., be used to set 6249 parameters such as the <link linkend="sendmail">$sendmail</link> 6250 variable depending on the message's sender address. 6251 </para> 6252 <para> 6253 For each type of <command>send-hook</command> or 6254 <command>reply-hook</command>, when multiple matches occur, commands 6255 are executed in the order they are specified in the 6256 <literal>.neomuttrc</literal> (for that type of hook). 6257 </para> 6258 <para> 6259 Example: 6260 <literal> 6261 <command>send-hook</command> work "<command>set</command> 6262 mime_forward signature=''" 6263 </literal> 6264 </para> 6265 <para> 6266 Another typical use for this command is to change the values of the 6267 <link linkend="attribution">$attribution</link>, 6268 <link linkend="attribution-locale">$attribution_locale</link>, and 6269 <link linkend="signature">$signature</link> variables in order to 6270 change the language of the attributions and signatures based upon the 6271 recipients. 6272 </para> 6273 <note> 6274 <para> 6275 <command>send-hook</command>'s are only executed once after getting the 6276 initial list of recipients. They are not executed when resuming a 6277 postponed draft. Adding a recipient after replying or editing the 6278 message will not cause any 6279 <command>send-hook</command> to be executed, similarly if 6280 <link linkend="auto-edit">$auto_edit</link> is set (as then the initial 6281 list of recipients is empty). Also note that 6282 <link linkend="my-hdr"><command>my_hdr</command></link> commands 6283 which modify recipient headers, or the message's subject, don't have 6284 any effect on the current message when executed from 6285 a <command>send-hook</command>. 6286 </para> 6287 </note> 6288 </sect1> 6289 6290 <sect1 id="message-hook"> 6291 <title>Change Settings Before Formatting a Message</title> 6292 <para> 6293 Usage: 6294 </para> 6295 <cmdsynopsis> 6296 <command>message-hook</command> 6297 <arg choice="plain"> 6298 <replaceable class="parameter">pattern</replaceable> 6299 </arg> 6300 <arg choice="plain"> 6301 <replaceable class="parameter">command</replaceable> 6302 </arg> 6303 </cmdsynopsis> 6304 <para> 6305 This command can be used to execute arbitrary configuration commands 6306 before viewing or formatting a message based upon information about the 6307 message. <emphasis>command</emphasis> is executed if the 6308 <emphasis>pattern</emphasis> matches the message to be displayed. When 6309 multiple matches occur, commands are executed in the order they are 6310 specified in the <literal>.neomuttrc</literal>. 6311 </para> 6312 <para> 6313 See <xref linkend="pattern-hook" /> for information on the exact format 6314 of <emphasis>pattern</emphasis>. 6315 </para> 6316 <para> 6317 Example: 6318 </para> 6319 6320<screen> 6321message-hook ~A 'set pager=builtin' 6322message-hook '~f freshmeat-news' 'set pager="less \"+/^ subject: .*\""' 6323</screen> 6324 6325 </sect1> 6326 6327 <sect1 id="crypt-hook"> 6328 <title>Choosing the Cryptographic Key of the Recipient</title> 6329 <para> 6330 Usage: 6331 </para> 6332 <cmdsynopsis> 6333 <command>crypt-hook</command> 6334 <arg choice="plain"> 6335 <replaceable class="parameter">regex</replaceable> 6336 </arg> 6337 <arg choice="plain"> 6338 <replaceable class="parameter">keyid</replaceable> 6339 </arg> 6340 </cmdsynopsis> 6341 <para> 6342 When encrypting messages with PGP/GnuPG or OpenSSL, you may want to 6343 associate a certain key with a given e-mail address automatically, 6344 either because the recipient's public key can't be deduced from the 6345 destination address, or because, for some reasons, you need to override 6346 the key NeoMutt would normally use. The <command>crypt-hook</command> 6347 command provides a method by which you can specify the ID of the public 6348 key to be used when encrypting messages to a certain recipient. You may 6349 use multiple crypt-hooks with the same regex; multiple matching 6350 crypt-hooks result in the use of multiple keyids for a recipient. 6351 During key selection, NeoMutt will confirm whether each crypt-hook is 6352 to be used (unless the 6353 <link linkend="crypt-confirm-hook">$crypt_confirm_hook</link> option is 6354 unset). If all crypt-hooks for a recipient are declined, NeoMutt will 6355 use the original recipient address for key selection instead. 6356 </para> 6357 <para> 6358 The meaning of <emphasis>keyid</emphasis> is to be taken broadly in 6359 this context: You can either put a numerical key ID or fingerprint 6360 here, an e-mail address, or even just a real name. 6361 </para> 6362 </sect1> 6363 6364 <sect1 id="index-format-hook"> 6365 <title>Dynamically Changing $index_format using Patterns</title> 6366 <para>Usage:</para> 6367 <cmdsynopsis> 6368 <command>index-format-hook</command> 6369 <arg choice="plain"> 6370 <replaceable class="parameter">name</replaceable> 6371 </arg> 6372 <arg choice="plain"> 6373 <replaceable class="parameter">[!]pattern</replaceable> 6374 </arg> 6375 <arg choice="plain"> 6376 <replaceable class="parameter">format-string</replaceable> 6377 </arg> 6378 </cmdsynopsis> 6379 <para> 6380 This command is used to inject format strings dynamically into <link 6381 linkend="index-format">$index_format</link>based on pattern matching 6382 against the current message. 6383 </para> 6384 <para> 6385 The <link linkend="index-format">$index_format</link>expando 6386 <emphasis>%@name@</emphasis>specifies a placeholder for the injection. 6387 Index-format-hooks with the same <emphasis>name</emphasis>are matched using 6388 <link linkend="patterns"> <emphasis>pattern</emphasis> </link>against the 6389 current message. Matching is done in the order specified in the .muttrc, 6390 with the first match being used. The hook's 6391 <emphasis>format-string</emphasis>is then substituted and evaluated. 6392 </para> 6393 <para> 6394 Because the first match is used, best practice is to put a catch-all 6395 <emphasis>~A</emphasis>pattern as the last hook. Here is an example showing 6396 how to implement dynamic date formatting: 6397 </para> 6398<screen> 6399set index_format="%4C %-6@date@ %-15.15F %Z (%4c) %s" 6400 6401index-format-hook date "~d<1d" "%[%H:%M]" 6402index-format-hook date "~d<1m" "%[%a %d]" 6403index-format-hook date "~d<1y" "%[%b %d]" 6404index-format-hook date "~A" "%[%m/%y]" 6405</screen> 6406 <para> 6407 Another example, showing a way to prepend to 6408 the subject. Note that without a catch-all ~A 6409 pattern, no match results in the expando being 6410 replaced with an empty string. 6411 </para> 6412<screen> 6413set index_format="%4C %@subj_flags@%s" 6414 6415index-format-hook subj_flags "~f boss@example.com" "** BOSS ** " 6416index-format-hook subj_flags "~f spouse@example.com" ":-) " 6417</screen> 6418 </sect1> 6419 6420 <sect1 id="push"> 6421 <title>Adding Key Sequences to the Keyboard Buffer</title> 6422 <para> 6423 Usage: 6424 </para> 6425 <cmdsynopsis> 6426 <command>push</command> 6427 <arg choice="plain"> 6428 <replaceable class="parameter">string</replaceable> 6429 </arg> 6430 </cmdsynopsis> 6431 <para> 6432 This command adds the named string to the beginning of the keyboard 6433 buffer. The string may contain control characters, key names and 6434 function names like the sequence string in the 6435 <link linkend="macro">macro</link> command. You may use it to 6436 automatically run a sequence of commands at startup, or when entering 6437 certain folders. For example, <xref linkend="ex-folder-hook-push" /> 6438 shows how to automatically collapse all threads when entering a folder. 6439 </para> 6440 <example id="ex-folder-hook-push"> 6441 <title>Embedding 6442 <command>push</command> in 6443 <command>folder-hook</command></title> 6444 <screen>folder-hook . 'push <collapse-all>'</screen> 6445 </example> 6446 <para> 6447 For using functions like shown in the example, it's important to use 6448 angle brackets (<quote><</quote> and <quote>></quote>) to make 6449 NeoMutt recognize the input as a function name. Otherwise it will 6450 simulate individual just keystrokes, i.e. 6451 <quote><literal>push collapse-all</literal></quote> would be 6452 interpreted as if you had typed <quote>c</quote>, followed by 6453 <quote>o</quote>, followed by <quote>l</quote>, ..., which is not 6454 desired and may lead to very unexpected behavior. 6455 </para> 6456 <para> 6457 Keystrokes can be used, too, but are less portable because of 6458 potentially changed key bindings. With default bindings, this is 6459 equivalent to the above example: 6460 </para> 6461 <screen>folder-hook . 'push \eV'</screen> 6462 <para> 6463 because it simulates that Esc+V was pressed (which is the default 6464 binding of <literal><collapse-all></literal>). 6465 </para> 6466 </sect1> 6467 6468 <sect1 id="exec"> 6469 <title>Executing Functions</title> 6470 <para> 6471 Usage: 6472 </para> 6473 <cmdsynopsis> 6474 <command>exec</command> 6475 <arg choice="plain"> 6476 <replaceable class="parameter">function</replaceable> 6477 </arg> 6478 <arg choice="opt" rep="repeat"> 6479 <replaceable class="parameter">function</replaceable> 6480 </arg> 6481 </cmdsynopsis> 6482 <para> 6483 This command can be used to execute any function. Functions are listed 6484 in the <link linkend="functions">function reference</link>. 6485 <quote><command>exec</command> <literal>function</literal></quote> is 6486 equivalent to <quote><literal>push <function></literal></quote>. 6487 </para> 6488 </sect1> 6489 6490 <sect1 id="score-command"> 6491 <title>Message Scoring</title> 6492 <para> 6493 Usage: 6494 </para> 6495 <cmdsynopsis> 6496 <command>score</command> 6497 <arg choice="plain"> 6498 <replaceable class="parameter">pattern</replaceable> 6499 </arg> 6500 <arg choice="plain"> 6501 <replaceable class="parameter">value</replaceable> 6502 </arg> 6503 <command>unscore</command> 6504 <group choice="req"> 6505 <arg choice="plain"> 6506 <replaceable class="parameter">*</replaceable> 6507 </arg> 6508 <arg choice="plain" rep="repeat"> 6509 <replaceable class="parameter">pattern</replaceable> 6510 </arg> 6511 </group> 6512 </cmdsynopsis> 6513 <para> 6514 The <command>score</command> commands adds <emphasis>value</emphasis> 6515 to a message's score if <emphasis>pattern</emphasis> matches it. 6516 <emphasis>pattern</emphasis> is a string in the format described in the 6517 <link linkend="patterns">patterns</link> section (note: For efficiency 6518 reasons, patterns which scan information not available in the index, 6519 such as <literal>~b</literal>, <literal>~B</literal>, 6520 <literal>~h</literal>, <literal>~M</literal>, or <literal>~X</literal> 6521 may not be used). <emphasis>value</emphasis> is a positive or negative 6522 integer. A message's final score is the sum total of all matching 6523 <command>score</command> entries. However, you may optionally prefix 6524 <emphasis>value</emphasis> with an equal sign (<quote>=</quote>) to 6525 cause evaluation to stop at a particular entry if there is a match. 6526 Negative final scores are rounded up to 0. 6527 </para> 6528 <para> 6529 The <command>unscore</command> command removes score entries from the 6530 list. You <emphasis>must</emphasis> specify the same pattern specified 6531 in the <command>score</command> command for it to be removed. The 6532 pattern <quote>*</quote> is a special token which means to clear the 6533 list of all score entries. 6534 </para> 6535 <para> 6536 Scoring occurs as the messages are read in, before the mailbox is 6537 sorted. Because of this, patterns which depend on threading, such as 6538 <emphasis>~=</emphasis>, <emphasis>~$</emphasis>, and 6539 <emphasis>~()</emphasis>, will not work by default. A workaround is to 6540 push the scoring command in a folder hook. This will cause the mailbox 6541 to be rescored after it is opened and input starts being processed: 6542 </para> 6543 6544<screen> 6545folder-hook . 'push "<enter-command>score ~= 10<enter>"' 6546</screen> 6547 6548 </sect1> 6549 6550 <sect1 id="spam"> 6551 <title>Spam Detection</title> 6552 <para> 6553 Usage: 6554 </para> 6555 <cmdsynopsis> 6556 <command>spam</command> 6557 <arg choice="plain"> 6558 <replaceable class="parameter">pattern</replaceable> 6559 </arg> 6560 <arg choice="plain"> 6561 <replaceable class="parameter">format</replaceable> 6562 </arg> 6563 <command>nospam</command> 6564 <group choice="req"> 6565 <arg choice="plain"> 6566 <replaceable class="parameter">*</replaceable> 6567 </arg> 6568 <arg choice="plain"> 6569 <replaceable class="parameter">pattern</replaceable> 6570 </arg> 6571 </group> 6572 </cmdsynopsis> 6573 <para> 6574 NeoMutt has generalized support for external spam-scoring filters. By 6575 defining your spam patterns with the <command>spam</command> and 6576 <literal>nospam</literal> commands, you can <emphasis>limit</emphasis>, 6577 <emphasis>search</emphasis>, and <emphasis>sort</emphasis> your mail 6578 based on its spam attributes, as determined by the external filter. You 6579 also can display the spam attributes in your index display using the 6580 <literal>%H</literal> selector in the 6581 <link linkend="index-format">$index_format</link> variable. (Tip: try 6582 <literal>%?H?[%H] ?</literal> to display spam tags only when they are 6583 defined for a given message.) 6584 </para> 6585 <para> 6586 Note: the value displayed by <literal>%H</literal>and searched by 6587 <literal>~H</literal>is stored in the 6588 <link linkend="caching">header cache</link>. NeoMutt isn't smart enough to 6589 invalidate a header cache entry based on changing <literal>spam</literal> 6590 rules, so if you aren't seeing correct <literal>%H</literal>values, try 6591 temporarily turning off the header cache. If that fixes the problem, 6592 then once your spam rules are set to your liking, remove your stale 6593 header cache files and turn the header cache back on. 6594 </para> 6595 <para> 6596 Your first step is to define your external filter's spam patterns using 6597 the <command>spam</command> command. <emphasis>pattern</emphasis> 6598 should be a regular expression that matches a header in a mail message. 6599 If any message in the mailbox matches this regular expression, it will 6600 receive a <quote>spam tag</quote> or <quote>spam attribute</quote> 6601 (unless it also matches a <command>nospam</command> pattern – see 6602 below.) The appearance of this attribute is entirely up to you, and is 6603 governed by the <emphasis>format</emphasis> parameter. 6604 <emphasis>format</emphasis> can be any static text, but it also can 6605 include back-references from the <emphasis>pattern</emphasis> 6606 expression. (A regular expression <quote>back-reference</quote> refers 6607 to a sub-expression contained within parentheses.) 6608 <literal>%1</literal> is replaced with the first back-reference in the 6609 regex, <literal>%2</literal> with the second, etc. 6610 </para> 6611 <para> 6612 To match spam tags, NeoMutt needs the corresponding header information 6613 which is always the case for local and POP folders but not for IMAP in 6614 the default configuration. Depending on the spam header to be analyzed, 6615 <link linkend="imap-headers">$imap_headers</link> may need to be 6616 adjusted. 6617 </para> 6618 <para> 6619 If you're using multiple spam filters, a message can have more than one 6620 spam-related header. You can define <command>spam</command> patterns 6621 for each filter you use. If a message matches two or more of these 6622 patterns, and the <link linkend="spam-separator">$spam_separator</link> 6623 variable is set to a string, then the message's spam tag will consist 6624 of all the <emphasis>format</emphasis> strings joined together, with 6625 the value of <link linkend="spam-separator">$spam_separator</link> 6626 separating them. 6627 </para> 6628 <para> 6629 For example, suppose one uses DCC, SpamAssassin, and PureMessage, then 6630 the configuration might look like in <xref linkend="ex-spam" />. 6631 </para> 6632 <example id="ex-spam"> 6633 <title>Configuring spam detection</title> 6634 6635<screen> 6636spam "X-DCC-.*-Metrics:.*(....)=many" "90+/DCC-%1" 6637spam "X-Spam-Status: Yes" "90+/SA" 6638spam "X-PerlMX-Spam: .*Probability=([0-9]+)%" "%1/PM" 6639set spam_separator=", " 6640</screen> 6641 6642 </example> 6643 <para> 6644 If then a message is received that DCC registered with 6645 <quote>many</quote> hits under the <quote>Fuz2</quote> checksum, and 6646 that PureMessage registered with a 97% probability of being spam, that 6647 message's spam tag would read <literal>90+/DCC-Fuz2, 97/PM</literal>. 6648 (The four characters before <quote>=many</quote> in a DCC report 6649 indicate the checksum used – in this case, <quote>Fuz2</quote>.) 6650 </para> 6651 <para> 6652 If the <link linkend="spam-separator">$spam_separator</link> variable 6653 is unset, then each spam pattern match supersedes the previous one. 6654 Instead of getting joined <emphasis>format</emphasis> strings, you'll 6655 get only the last one to match. 6656 </para> 6657 <para> 6658 The spam tag is what will be displayed in the index when you use 6659 <literal>%H</literal> in the 6660 <link linkend="index-format">$index_format</link> variable. It's also 6661 the string that the <literal>~H</literal> pattern-matching expression 6662 matches against for <literal><search></literal> and 6663 <literal><limit></literal> functions. And it's what sorting by 6664 spam attribute will use as a sort key. 6665 </para> 6666 <para> 6667 That's a pretty complicated example, and most people's actual 6668 environments will have only one spam filter. The simpler your 6669 configuration, the more effective NeoMutt can be, especially when it 6670 comes to sorting. 6671 </para> 6672 <para> 6673 Generally, when you sort by spam tag, NeoMutt will sort 6674 <emphasis>lexically</emphasis> – that is, by ordering strings 6675 alphanumerically. However, if a spam tag begins with a number, NeoMutt 6676 will sort numerically first, and lexically only when two numbers are 6677 equal in value. (This is like UNIX's <literal>sort -n</literal>.) 6678 A message with no spam attributes at all – that is, one that didn't 6679 match <emphasis>any</emphasis> of your <command>spam</command> patterns 6680 – is sorted at lowest priority. Numbers are sorted next, beginning with 6681 0 and ranging upward. Finally, non-numeric strings are sorted, with 6682 <quote>a</quote> taking lower priority than <quote>z</quote>. Clearly, 6683 in general, sorting by spam tags is most effective when you can coerce 6684 your filter to give you a raw number. But in case you can't, NeoMutt 6685 can still do something useful. 6686 </para> 6687 <para> 6688 The <command>nospam</command> command can be used to write exceptions 6689 to <command>spam</command> patterns. If a header pattern matches 6690 something in a <command>spam</command> command, but you nonetheless do 6691 not want it to receive a spam tag, you can list a more precise pattern 6692 under a <command>nospam</command> command. 6693 </para> 6694 <para> 6695 If the <emphasis>pattern</emphasis> given to <command>nospam</command> 6696 is exactly the same as the <emphasis>pattern</emphasis> on an existing 6697 <command>spam</command> list entry, the effect will be to remove the 6698 entry from the spam list, instead of adding an exception. Likewise, if 6699 the <emphasis>pattern</emphasis> for a <command>spam</command> command 6700 matches an entry on the <command>nospam</command> list, that nospam 6701 entry will be removed. If the <emphasis>pattern</emphasis> for 6702 <command>nospam</command> is <quote>*</quote>, 6703 <emphasis>all entries on both lists</emphasis> will be removed. This 6704 might be the default action if you use <command>spam</command> and 6705 <command>nospam</command> in conjunction with 6706 a <command>folder-hook</command>. 6707 </para> 6708 <para> 6709 You can have as many <command>spam</command> or 6710 <command>nospam</command> commands as you like. You can even do your 6711 own primitive <command>spam</command> detection within NeoMutt – for 6712 example, if you consider all mail from <literal>MAILER-DAEMON</literal> 6713 to be spam, you can use a <command>spam</command> command like this: 6714 </para> 6715 <screen>spam "^From: .*MAILER-DAEMON" "999"</screen> 6716 </sect1> 6717 6718 <sect1 id="set"> 6719 <title>Setting and Querying Variables</title> 6720 6721 <sect2 id="var-types"> 6722 <title>Variable Types</title> 6723 <para> 6724 NeoMutt supports these types of configuration variables: 6725 </para> 6726 <variablelist> 6727 <varlistentry> 6728 <term>boolean</term> 6729 <listitem> 6730 <para> 6731 A boolean expression, either <quote>yes</quote> or 6732 <quote>no</quote>. 6733 </para> 6734 </listitem> 6735 </varlistentry> 6736 <varlistentry> 6737 <term>number</term> 6738 <listitem> 6739 <para> 6740 A signed integer number in the range -32768 to 32767. 6741 </para> 6742 </listitem> 6743 </varlistentry> 6744 <varlistentry> 6745 <term>number (long)</term> 6746 <listitem> 6747 <para> 6748 A signed integer number in the range -2147483648 to 2147483647. 6749 </para> 6750 </listitem> 6751 </varlistentry> 6752 <varlistentry> 6753 <term>string</term> 6754 <listitem> 6755 <para> 6756 Arbitrary text. 6757 </para> 6758 </listitem> 6759 </varlistentry> 6760 <varlistentry> 6761 <term>path</term> 6762 <listitem> 6763 <para> 6764 A specialized string for representing paths including support 6765 for mailbox shortcuts (see <xref linkend="shortcuts" />) as 6766 well as tilde (<quote>~</quote>) for a user's home directory 6767 and more. 6768 </para> 6769 </listitem> 6770 </varlistentry> 6771 <varlistentry> 6772 <term>quadoption</term> 6773 <listitem> 6774 <para> 6775 Like a boolean but triggers a prompt when set to 6776 <quote>ask-yes</quote> or <quote>ask-no</quote> with 6777 <quote>yes</quote> and <quote>no</quote> preselected 6778 respectively. 6779 </para> 6780 </listitem> 6781 </varlistentry> 6782 <varlistentry> 6783 <term>sort order</term> 6784 <listitem> 6785 <para> 6786 A specialized string allowing only particular words as values 6787 depending on the variable. 6788 </para> 6789 </listitem> 6790 </varlistentry> 6791 <varlistentry> 6792 <term>regular expression</term> 6793 <listitem> 6794 <para> 6795 A regular expression, see <xref linkend="regex" /> for an 6796 introduction. 6797 </para> 6798 </listitem> 6799 </varlistentry> 6800 <varlistentry> 6801 <term>folder type</term> 6802 <listitem> 6803 <para> 6804 Specifies the type of folder to use: <emphasis>mbox</emphasis>, 6805 <emphasis>mmdf</emphasis>, <emphasis>mh</emphasis> or 6806 <emphasis>maildir</emphasis>. Currently only used to determine 6807 the type for newly created folders. 6808 </para> 6809 </listitem> 6810 </varlistentry> 6811 <varlistentry> 6812 <term>e-mail address</term> 6813 <listitem> 6814 <para> 6815 An email address either with or without real_name. The older 6816 <quote><literal>user@example.org (Joe User)</literal></quote> 6817 form is supported but strongly deprecated. 6818 </para> 6819 </listitem> 6820 </varlistentry> 6821 <varlistentry> 6822 <term>user-defined</term> 6823 <listitem> 6824 <para> 6825 Arbitrary text, see <xref linkend="set-myvar" /> for details. 6826 </para> 6827 </listitem> 6828 </varlistentry> 6829 </variablelist> 6830 </sect2> 6831 6832 <sect2 id="set-commands"> 6833 <title>Commands</title> 6834 <para> 6835 The following commands are available to manipulate and query 6836 variables: 6837 </para> 6838 <para> 6839 Usage: 6840 </para> 6841 <cmdsynopsis> 6842 <command>set</command> 6843 <group choice="req"> 6844 <arg choice="plain"> 6845 <group choice="opt"> 6846 <arg choice="plain"> 6847 <option>no</option> 6848 </arg> 6849 <arg choice="plain"> 6850 <option>inv</option> 6851 </arg> 6852 <arg choice="plain"> 6853 <option>&</option> 6854 </arg> 6855 <arg choice="plain"> 6856 <option>?</option> 6857 </arg> 6858 </group> 6859 <replaceable class="parameter">variable</replaceable> 6860 </arg> 6861 </group> 6862 <arg choice="opt" rep="repeat"></arg> 6863 <command>set</command> 6864 <group choice="req"> 6865 <arg choice="plain"> 6866 <replaceable class="parameter">variable=value</replaceable> 6867 </arg> 6868 <arg choice="plain"> 6869 <replaceable class="parameter">variable+=increment</replaceable> 6870 </arg> 6871 <arg choice="plain"> 6872 <replaceable class="parameter">variable-=decrement</replaceable> 6873 </arg> 6874 </group> 6875 <arg choice="opt" rep="repeat"></arg> 6876 <command>unset</command> 6877 <arg choice="plain"> 6878 <replaceable class="parameter">variable</replaceable> 6879 </arg> 6880 <arg choice="opt" rep="repeat"> 6881 <replaceable class="parameter">variable</replaceable> 6882 </arg> 6883 <command>reset</command> 6884 <arg choice="plain"> 6885 <replaceable class="parameter">variable</replaceable> 6886 </arg> 6887 <arg choice="opt" rep="repeat"> 6888 <replaceable class="parameter">variable</replaceable> 6889 </arg> 6890 <command>toggle</command> 6891 <arg choice="plain"> 6892 <replaceable class="parameter">variable</replaceable> 6893 </arg> 6894 <arg choice="opt" rep="repeat"> 6895 <replaceable class="parameter">variable</replaceable> 6896 </arg> 6897 </cmdsynopsis> 6898 <para> 6899 This command is used to set (and unset) 6900 <link linkend="variables">configuration variables</link>. There are 6901 several basic types of variables: boolean, number, string, string list 6902 and quadoption. <emphasis>boolean</emphasis> variables can be 6903 <emphasis>set</emphasis> (true) or <emphasis>unset</emphasis> 6904 (false). <emphasis>number</emphasis> variables can be assigned 6905 a positive integer value. The value of numeric variables can be 6906 incremented <emphasis>+=</emphasis> and decremented 6907 <emphasis>-=</emphasis>. <emphasis>String list</emphasis> variables 6908 use <emphasis>+=</emphasis> for appending to the string list 6909 and <emphasis>-=</emphasis> for removal from the string list. 6910 <emphasis>string</emphasis> variables 6911 consist of any number of printable characters and must be enclosed in 6912 quotes if they contain spaces or tabs. You may also use the escape 6913 sequences <quote>\n</quote> and <quote>\t</quote> for newline and 6914 tab, respectively. Content of a <emphasis>string</emphasis> variable 6915 can be extended using <emphasis>+=</emphasis>. 6916 <emphasis>quadoption</emphasis> variables are used to control whether 6917 or not to be prompted for certain actions, or to specify a default action. 6918 A value of <emphasis>yes</emphasis> will cause the action to be carried 6919 out automatically as if you had answered yes to the question. Similarly, 6920 a value of <emphasis>no</emphasis> will cause the action to be carried 6921 out as if you had answered <quote>no.</quote> A value of 6922 <emphasis>ask-yes</emphasis> will cause a prompt with a default 6923 answer of <quote>yes</quote> and <emphasis>ask-no</emphasis> will 6924 provide a default answer of <quote>no.</quote> 6925 </para> 6926 <para> 6927 Prefixing a variable with <quote>no</quote> will unset it. Example: 6928 <literal><command>set</command> noask_bcc</literal>. 6929 </para> 6930 <para> 6931 For <emphasis>boolean</emphasis> variables, you may optionally prefix 6932 the variable name with <literal>inv</literal> to toggle the value (on 6933 or off). This is useful when writing macros. Example: 6934 <literal><command>set</command> invsmart_wrap</literal>. 6935 </para> 6936 <para> 6937 The <command>toggle</command> command automatically prepends the 6938 <literal>inv</literal> prefix to all specified variables. 6939 </para> 6940 <para> 6941 The <command>unset</command> command automatically prepends the 6942 <literal>no</literal> prefix to all specified variables. 6943 </para> 6944 <para> 6945 Using the <literal><enter-command></literal> function in the 6946 <emphasis>index</emphasis> menu, you can query the value of 6947 a variable by prefixing the name of the variable with a question 6948 mark: 6949 </para> 6950 <screen>set ?allow_8bit</screen> 6951 <para> 6952 The question mark is actually only required for boolean and 6953 quadoption variables. 6954 </para> 6955 <para> 6956 The <command>reset</command> command resets all given variables to 6957 the compile time defaults (hopefully mentioned in this manual). If 6958 you use the command <command>set</command> and prefix the variable 6959 with <quote>&</quote> this has the same behavior as the 6960 <command>reset</command> command. 6961 </para> 6962 <para> 6963 With the <command>reset</command> command there exists the special 6964 variable <quote>all</quote>, which allows you to reset all variables 6965 to their system defaults. 6966 </para> 6967 </sect2> 6968 6969 <sect2 id="set-myvar"> 6970 <title>User-Defined Variables</title> 6971 6972 <sect3 id="set-myvar-intro"> 6973 <title>Introduction</title> 6974 <para> 6975 Along with the variables listed in the 6976 <link linkend="variables">Configuration variables</link> section, 6977 NeoMutt supports user-defined variables with names starting with 6978 <literal>my_</literal> as in, for example, 6979 <literal>my_cfgdir</literal>. 6980 </para> 6981 <para> 6982 The <command>set</command> command either creates a custom 6983 <literal>my_</literal> variable or changes its value if it 6984 exists already. Use of <emphasis>+=</emphasis> will adjust 6985 a custom variable using the same behavior as a string 6986 variable, by appending additional characters (this is true 6987 even if the current contents of the variable resemble an 6988 integer, which is different than the behavior of 6989 <emphasis>+=</emphasis> on built-in numeric 6990 variables). The <command>unset</command> and 6991 <command>reset</command> commands remove the variable 6992 entirely. 6993 </para> 6994 <para> 6995 Since user-defined variables are expanded in the same way that 6996 environment variables are (except for the 6997 <link linkend="shell-escape">shell-escape</link> command and 6998 backtick expansion), this feature can be used to make configuration 6999 files more readable. 7000 </para> 7001 </sect3> 7002 7003 <sect3 id="set-myvar-examples"> 7004 <title>Examples</title> 7005 <para> 7006 The following example defines and uses the variable 7007 <literal>my_cfgdir</literal> to abbreviate the calls of the 7008 <link linkend="source"><command>source</command></link> command: 7009 </para> 7010 <example id="ex-myvar1"> 7011 <title>Using user-defined variables for config file 7012 readability</title> 7013 7014<screen> 7015set my_cfgdir = $HOME/neomutt/config 7016source $my_cfgdir/hooks $my_cfgdir/macros 7017<emphasis role="comment"># more source commands...</emphasis> 7018</screen> 7019 7020 </example> 7021 <para> 7022 A custom variable can also be used in macros to backup the current 7023 value of another variable. In the following example, the value of 7024 the <link linkend="delete">$delete</link> is changed temporarily 7025 while its original value is saved as <literal>my_delete</literal>. 7026 After the macro has executed all commands, the original value of 7027 <link linkend="delete">$delete</link> is restored. 7028 </para> 7029 <example id="ex-myvar2"> 7030 <title>Using user-defined variables for backing up other config 7031 option values</title> 7032 7033<screen> 7034macro pager ,x '\ 7035<enter-command>set my_delete=$delete<enter>\ 7036<enter-command>set delete=yes<enter>\ 7037...\ 7038<enter-command>set delete=$my_delete<enter>' 7039</screen> 7040 7041 </example> 7042 <para> 7043 Since NeoMutt expands such values already when parsing the 7044 configuration file(s), the value of <literal>$my_delete</literal> 7045 in the last example would be the value of 7046 <link linkend="delete">$delete</link> exactly as it was at that 7047 point during parsing the configuration file. If another statement 7048 would change the value for <link linkend="delete">$delete</link> 7049 later in the same or another file, it would have no effect on 7050 <literal>$my_delete</literal>. However, the expansion can be 7051 deferred to runtime, as shown in the next example, when escaping 7052 the dollar sign. 7053 </para> 7054 <example id="ex-myvar3"> 7055 <title>Deferring user-defined variable expansion to runtime</title> 7056 7057<screen> 7058macro pager <PageDown> "\ 7059<enter-command> set my_old_pager_stop=\$pager_stop pager_stop<Enter>\ 7060<next-page>\ 7061<enter-command> set pager_stop=\$my_old_pager_stop<Enter>\ 7062<enter-command> unset my_old_pager_stop<Enter>" 7063</screen> 7064 7065 </example> 7066 <para> 7067 Note that there is a space between 7068 <literal><enter-command></literal> and the 7069 <command>set</command> configuration command, preventing NeoMutt 7070 from recording the <command>macro</command>'s commands into its 7071 history. 7072 </para> 7073 </sect3> 7074 </sect2> 7075 7076 <sect2 id="set-conversions"> 7077 <title>Type Conversions</title> 7078 <para> 7079 Variables are always assigned string values which NeoMutt parses into 7080 its internal representation according to the type of the variable, 7081 for example an integer number for numeric types. For all queries 7082 (including $-expansion) the value is converted from its internal type 7083 back into string. As a result, any variable can be assigned any value 7084 given that its content is valid for the target. This also counts for 7085 custom variables which are of type string. In case of parsing errors, 7086 NeoMutt will print error messages. <xref linkend="ex-myvar4" /> 7087 demonstrates type conversions. 7088 </para> 7089 <example id="ex-myvar4"> 7090 <title>Type conversions using variables</title> 7091 7092<screen> 7093set my_lines = "5" <emphasis role="comment"># value is string "5"</emphasis> 7094set pager_index_lines = $my_lines <emphasis role="comment"># value is integer 5</emphasis> 7095set my_sort = "date-received" <emphasis role="comment"># value is string "date-received"</emphasis> 7096set sort = "last-$my_sort" <emphasis role="comment"># value is sort last-date-received</emphasis> 7097set my_inc = $read_inc <emphasis role="comment"># value is string "10" (default of $read_inc)</emphasis> 7098set my_foo = $my_inc <emphasis role="comment"># value is string "10"</emphasis> 7099</screen> 7100 7101 </example> 7102 <para> 7103 These assignments are all valid. If, however, the value of 7104 <literal>$my_lines</literal> would have been <quote>five</quote> (or 7105 something else that cannot be parsed into a number), the assignment 7106 to <literal>$pager_index_lines</literal> would have produced an error 7107 message. 7108 </para> 7109 <para> 7110 Type conversion applies to all configuration commands which take 7111 arguments. But please note that every expanded value of a variable is 7112 considered just a single token. A working example is: 7113 </para> 7114 7115<screen> 7116set my_pattern = "~A" 7117set my_number = "10" 7118<emphasis role="comment"># same as: score ~A +10</emphasis> 7119score $my_pattern +$my_number 7120</screen> 7121 7122 <para> 7123 What does <emphasis>not</emphasis> work is: 7124 </para> 7125 7126<screen> 7127set my_mx = "+mailbox1 +mailbox2" 7128mailboxes $my_mx +mailbox3 7129</screen> 7130 7131 <para> 7132 because the value of <literal>$my_mx</literal> is interpreted as 7133 a single mailbox named <quote>+mailbox1 +mailbox2</quote> and not two 7134 distinct mailboxes. 7135 </para> 7136 </sect2> 7137 </sect1> 7138 7139 <sect1 id="source"> 7140 <title>Reading Initialization Commands From Another File</title> 7141 <para> 7142 Usage: 7143 </para> 7144 <cmdsynopsis> 7145 <command>source</command> 7146 <arg choice="plain"> 7147 <replaceable class="parameter">filename</replaceable> 7148 </arg> 7149 </cmdsynopsis> 7150 <para> 7151 This command allows the inclusion of initialization commands from other 7152 files. For example, I place all of my aliases in 7153 <literal>~/.mail_aliases</literal> so that I can make my 7154 <literal>~/.neomuttrc</literal> readable and keep my aliases private. 7155 </para> 7156 <para> 7157 If the filename begins with a tilde (<quote>~</quote>), it will be 7158 expanded to the path of your home directory. 7159 </para> 7160 <para> 7161 If the filename ends with a vertical bar (<quote>|</quote>), then 7162 <emphasis>filename</emphasis> is considered to be an executable program 7163 from which to read input (e.g. 7164 <literal><command>source</command> ~/bin/myscript|</literal>). 7165 </para> 7166 </sect1> 7167 7168 <sect1 id="unhook"> 7169 <title>Removing Hooks</title> 7170 <para> 7171 Usage: 7172 </para> 7173 <cmdsynopsis> 7174 <command>unhook</command> 7175 <group choice="req"> 7176 <arg choice="plain"> 7177 <replaceable class="parameter">*</replaceable> 7178 </arg> 7179 <arg choice="plain"> 7180 <replaceable class="parameter">hook-type</replaceable> 7181 </arg> 7182 </group> 7183 </cmdsynopsis> 7184 <para> 7185 This command permits you to flush hooks you have previously defined. 7186 You can either remove all hooks by giving the <quote>*</quote> 7187 character as an argument, or you can remove all hooks of a specific 7188 type by saying something like 7189 <literal><command>unhook</command> send-hook</literal>. 7190 </para> 7191 </sect1> 7192 7193 <sect1 id="formatstrings"> 7194 <title>Format Strings</title> 7195 7196 <sect2 id="formatstrings-basics"> 7197 <title>Basic usage</title> 7198 <para> 7199 Format strings are a general concept you'll find in several locations 7200 through the NeoMutt configuration, especially in the 7201 <link linkend="index-format">$index_format</link>, 7202 <link linkend="pager-format">$pager_format</link>, 7203 <link linkend="status-format">$status_format</link>, and other 7204 related variables. These can be very straightforward, and it's quite 7205 possible you already know how to use them. 7206 </para> 7207 <para> 7208 The most basic format string element is a percent symbol followed by 7209 another character. For example, <literal>%s</literal> represents 7210 a message's Subject: header in the 7211 <link linkend="index-format">$index_format</link> variable. The 7212 <quote>expandos</quote> available are documented with each format 7213 variable, but there are general modifiers available with all 7214 formatting expandos, too. Those are our concern here. 7215 </para> 7216 <para> 7217 Some of the modifiers are borrowed right out of C (though you might 7218 know them from Perl, Python, shell, or another language). These are 7219 the <literal>[-]m.n</literal> modifiers, as in 7220 <literal>%-12.12s</literal>. As with such programming languages, 7221 these modifiers allow you to specify the minimum and maximum size of 7222 the resulting string, as well as its justification. If the 7223 <quote>-</quote> sign follows the percent, the string will be 7224 left-justified instead of right-justified. If there's a number 7225 immediately following that, it's the minimum amount of space the 7226 formatted string will occupy – if it's naturally smaller than that, 7227 it will be padded out with spaces. If a decimal point and another 7228 number follow, that's the maximum space allowable – the string will 7229 not be permitted to exceed that width, no matter its natural size. 7230 Each of these three elements is optional, so that all these are legal 7231 format strings: <literal>%-12s</literal>, <literal>%4c</literal>, 7232 <literal>%.15F</literal> and <literal>%-12.15L</literal>. 7233 </para> 7234 <para> 7235 NeoMutt adds some other modifiers to format strings. If you use an 7236 equals symbol (<literal>=</literal>) as a numeric prefix (like the 7237 minus above), it will force the string to be centered within its 7238 minimum space range. For example, <literal>%=14y</literal> will 7239 reserve 14 characters for the %y expansion – that's the set of 7240 message keywords (formerly X-Label). If the expansion results in 7241 a string less than 14 characters, it will be centered in 7242 a 14-character space. If the X-Label for a message were 7243 <quote>test</quote>, that expansion would look like 7244 <quote>     test     </quote>. 7245 </para> 7246 <para> 7247 There are two very little-known modifiers that affect the way that an 7248 expando is replaced. If there is an underline (<quote>_</quote>) 7249 character between any format modifiers (as above) and the expando 7250 letter, it will expands in all lower case. And if you use a colon 7251 (<quote>:</quote>), it will replace all decimal points with 7252 underlines. 7253 </para> 7254 </sect2> 7255 7256 <sect2 id="formatstrings-conditionals"> 7257 <title>Conditionals</title> 7258 <para> 7259 Depending on the format string variable, some of its sequences can be 7260 used to optionally print a string if their value is nonzero. For 7261 example, you may only want to see the number of flagged messages if 7262 such messages exist, since zero is not particularly meaningful. To 7263 optionally print a string based upon one of the above sequences, the 7264 following construct is used: 7265 </para> 7266 <screen>%?<sequence_char>?<optional_string>?</screen> 7267 <para> 7268 where <emphasis>sequence_char</emphasis> is an expando, and 7269 <emphasis>optional_string</emphasis> is the string you would like 7270 printed if <emphasis>sequence_char</emphasis> is nonzero. 7271 <emphasis>optional_string</emphasis> may contain other sequences as 7272 well as normal text, but you may not nest optional strings. 7273 </para> 7274 <para> 7275 Here is an example illustrating how to optionally print the number of 7276 new messages in a mailbox in 7277 <link linkend="status-format">$status_format</link>: 7278 </para> 7279 <screen>%?n?%n new messages.?</screen> 7280 <para> 7281 You can also switch between two strings using the following 7282 construct: 7283 </para> 7284 7285<screen> 7286%?<sequence_char>?<if_string>&<else_string>? 7287</screen> 7288 7289 <para> 7290 If the value of <emphasis>sequence_char</emphasis> is non-zero, 7291 <emphasis>if_string</emphasis> will be expanded, otherwise 7292 <emphasis>else_string</emphasis> will be expanded. 7293 </para> 7294 <para> 7295 The conditional sequences can also be nested by using the %< and 7296 > operators. The %? notation can still be used but requires 7297 quoting. For example: 7298 </para> 7299 7300<screen> 7301%<x?true&false> 7302%<x?%<y?%<z?xyz&xy>&x>&none> 7303</screen> 7304 7305 <para> 7306 For more examples, see <xref linkend="nested-if" /> 7307 </para> 7308 </sect2> 7309 7310 <sect2 id="formatstrings-filters"> 7311 <title>Filters</title> 7312 <para> 7313 Any format string ending in a vertical bar (<quote>|</quote>) will 7314 be expanded and piped through the first word in the string, using 7315 spaces as separator. The string returned will be used for display. If 7316 the returned string ends in %, it will be passed through the 7317 formatter a second time. This allows the filter to generate 7318 a replacement format string including % expandos. 7319 </para> 7320 <para> 7321 All % expandos in a format string are expanded before the script is 7322 called so that: 7323 </para> 7324 <example id="ex-fmtpipe"> 7325 <title>Using external filters in format strings</title> 7326 <screen>set status_format="script.sh '%r %f (%L)'|"</screen> 7327 </example> 7328 <para> 7329 will make NeoMutt expand <literal>%r</literal>, <literal>%f</literal> 7330 and <literal>%L</literal> before calling the script. The example also 7331 shows that arguments can be quoted: the script will receive the 7332 expanded string between the single quotes as the only argument. 7333 </para> 7334 <para> 7335 A practical example is the <literal>mutt_xtitle</literal> script 7336 installed in the <literal>samples</literal> subdirectory of the 7337 NeoMutt documentation: it can be used as filter for 7338 <link linkend="status-format">$status_format</link> to set the 7339 current terminal's title, if supported. 7340 </para> 7341 </sect2> 7342 7343 <sect2 id="formatstrings-padding"> 7344 <title>Padding</title> 7345 <para> 7346 In most format strings, NeoMutt supports different types of padding 7347 using special %-expandos: 7348 </para> 7349 <variablelist> 7350 <varlistentry> 7351 <term> 7352 <literal>%|X</literal> 7353 </term> 7354 <listitem> 7355 <para> 7356 When this occurs, NeoMutt will fill the rest of the line with 7357 the character <literal>X</literal>. For example, filling the 7358 rest of the line with dashes is done by setting: 7359 </para> 7360 7361<screen> 7362set status_format = "%v on %h: %B: %?n?%n&no? new messages %|-" 7363</screen> 7364 7365 </listitem> 7366 </varlistentry> 7367 <varlistentry> 7368 <term> 7369 <literal>%>X</literal> 7370 </term> 7371 <listitem> 7372 <para> 7373 Since the previous expando stops at the end of line, there must 7374 be a way to fill the gap between two items via the 7375 <literal>%>X</literal> expando: it puts as many characters 7376 <literal>X</literal> in between two items so that the rest of 7377 the line will be right-justified. For example, to not put the 7378 version string and hostname the above example on the left but 7379 on the right and fill the gap with spaces, one might use (note 7380 the space after <literal>%></literal>): 7381 </para> 7382 7383<screen> 7384set status_format = "%B: %?n?%n&no? new messages %> (%v on %h)" 7385</screen> 7386 7387 </listitem> 7388 </varlistentry> 7389 <varlistentry> 7390 <term> 7391 <literal>%*X</literal> 7392 </term> 7393 <listitem> 7394 <para> 7395 Normal right-justification will print everything to the left of 7396 the <literal>%></literal>, displaying padding and whatever 7397 lies to the right only if there's room. By contrast, 7398 <quote>soft-fill</quote> gives priority to the right-hand side, 7399 guaranteeing space to display it and showing padding only if 7400 there's still room. If necessary, soft-fill will eat text 7401 leftwards to make room for rightward text. For example, to 7402 right-justify the subject making sure as much as possible of it 7403 fits on screen, one might use (note two spaces after 7404 <literal>%*</literal>: the second ensures there's a space 7405 between the truncated right-hand side and the subject): 7406 </para> 7407 7408<screen> 7409set index_format="%4C %Z %{%b %d} %-15.15L (%?l?%4l&%4c?)%* %s" 7410</screen> 7411 7412 </listitem> 7413 </varlistentry> 7414 </variablelist> 7415 </sect2> 7416 7417 <sect2 id="formatstrings-conditional-dates"> 7418 <title>Conditional Dates</title> 7419 <para> 7420 This feature allows the format of dates in the index to vary based on 7421 how recent the message is. This is especially useful in combination 7422 with the <link linkend="nested-if">nested-if feature</link>. 7423 </para> 7424 <para> 7425 For example, using 7426 <literal>%<[y?%<[d?%[%H:%M]&%[%m/%d]>&%[%y.%m]></literal> 7427 for the date in the <literal>$index_format</literal> will produce 7428 a display like: 7429 </para> 7430 7431<screen> 7432 1 + 14.12 Grace Hall ( 13) Gulliver's Travels 7433 2 + 10/02 Callum Harrison ( 48) Huckleberry Finn 7434 3 12:17 Rhys Lee ( 42) The Lord Of The Rings 7435</screen> 7436 7437 </sect2> 7438 7439 <sect2 id="formatstrings-size"> 7440 <title>Bytes size display</title> 7441 7442 <para> 7443 Various format strings contain expandos that display the size of 7444 messages in bytes. This includes 7445 <literal>%s</literal> in <link linkend="attach-format">$attach_format</link>, 7446 <literal>%l</literal> in <link linkend="compose-format">$compose_format</link>, 7447 <literal>%s</literal> in <link linkend="folder-format">$folder_format</link>, 7448 <literal>%c</literal> and <literal>%cr</literal> 7449 in <link linkend="index-format">$index_format</link>, 7450 and %l and %L in <link linkend="status-format">$status_format</link>. 7451 There are four configuration variables that can be used to customize 7452 how the numbers are displayed. 7453 </para> 7454 7455 <para> 7456 <link linkend="size-show-bytes">$size_show_bytes</link> 7457 will display the number of bytes when the size is < 1 7458 kilobyte. When unset, kilobytes will be displayed instead. 7459 </para> 7460 7461 <para> 7462 <link linkend="size-show-mb">$size_show_mb</link> will display the 7463 number of megabytes when the size is >= 1 megabyte. When 7464 unset, kilobytes will be displayed instead (which could be a large 7465 number). 7466 </para> 7467 7468 <para> 7469 <link linkend="size-show-fractions">$size_show_fractions</link>, 7470 will display numbers with a single decimal place for values from 7471 0 to 10 kilobytes, and 1 to 10 megabytes. 7472 </para> 7473 7474 <para> 7475 <link linkend="size-units-on-left">$size_units_on_left</link> will 7476 display the unit (<quote>K</quote> or <quote>M</quote>) to the left 7477 of the number, instead of the right if unset. 7478 </para> 7479 7480 <para> 7481 These variables also affect size display in a few other places, such 7482 as progress indicators and attachment delimiters in the pager. 7483 </para> 7484 </sect2> 7485 </sect1> 7486 7487 <sect1 id="mailto-allow"> 7488 <title>Control allowed header fields in a mailto: URL</title> 7489 <para> 7490 Usage: 7491 </para> 7492 <cmdsynopsis> 7493 <command>mailto_allow</command> 7494 <group choice="req"> 7495 <arg choice="plain"> 7496 <replaceable class="parameter">*</replaceable> 7497 </arg> 7498 <arg choice="plain" rep="repeat"> 7499 <replaceable class="parameter">header-field</replaceable> 7500 </arg> 7501 </group> 7502 <command>unmailto_allow</command> 7503 <group choice="req"> 7504 <arg choice="plain"> 7505 <replaceable class="parameter">*</replaceable> 7506 </arg> 7507 <arg choice="plain" rep="repeat"> 7508 <replaceable class="parameter">header-field</replaceable> 7509 </arg> 7510 </group> 7511 </cmdsynopsis> 7512 <para> 7513 As a security measure, NeoMutt will only add user-approved header 7514 fields from a <literal>mailto:</literal> URL. This is necessary since 7515 NeoMutt will handle certain header fields, such as 7516 <literal>Attach:</literal>, in a special way. The 7517 <literal>mailto_allow</literal> and <literal>unmailto_allow</literal> 7518 commands allow the user to modify the list of approved headers. 7519 </para> 7520 <para> 7521 NeoMutt initializes the default list to contain only the 7522 <literal>Subject</literal> and <literal>Body</literal> header fields, 7523 which are the only requirement specified by the 7524 <literal>mailto:</literal> specification in RFC2368, and the 7525 <literal>Cc</literal>, <literal>In-Reply-To</literal>, 7526 <literal>References</literal> headers to aid with replies to mailing 7527 lists. 7528 </para> 7529 </sect1> 7530 </chapter> 7531 7532 <chapter id="advancedusage"> 7533 <title>Advanced Usage</title> 7534 7535 <sect1 id="charset-handling"> 7536 <title>Character Set Handling</title> 7537 <para> 7538 A <quote>character set</quote> is basically a mapping between bytes and 7539 glyphs and implies a certain character encoding scheme. For example, 7540 for the ISO 8859 family of character sets, an encoding of 8bit per 7541 character is used. For the Unicode character set, different character 7542 encodings may be used, UTF-8 being the most popular. In UTF-8, 7543 a character is represented using a variable number of bytes ranging 7544 from 1 to 4. 7545 </para> 7546 <para> 7547 Since NeoMutt is a command-line tool run from a shell, and delegates 7548 certain tasks to external tools (such as an editor for 7549 composing/editing messages), all of these tools need to agree on 7550 a character set and encoding. There exists no way to reliably deduce 7551 the character set a plain text file has. Interoperability is gained by 7552 the use of well-defined environment variables. The full set can be 7553 printed by issuing <literal>locale</literal> on the command line. 7554 </para> 7555 <para> 7556 Upon startup, NeoMutt determines the character set on its own using 7557 routines that inspect locale-specific environment variables. Therefore, 7558 it is generally not necessary to set the <literal>$charset</literal> 7559 variable in NeoMutt. It may even be counter-productive as NeoMutt uses 7560 system and library functions that derive the character set themselves 7561 and on which NeoMutt has no influence. It's safest to let NeoMutt work 7562 out the locale setup itself. 7563 </para> 7564 <para> 7565 If you happen to work with several character sets on a regular basis, 7566 it's highly advisable to use Unicode and an UTF-8 locale. Unicode can 7567 represent nearly all characters in a message at the same time. When not 7568 using a Unicode locale, it may happen that you receive messages with 7569 characters not representable in your locale. When displaying such 7570 a message, or replying to or forwarding it, information may get lost 7571 possibly rendering the message unusable (not only for you but also for 7572 the recipient, this breakage is not reversible as lost information 7573 cannot be guessed). 7574 </para> 7575 <para> 7576 A Unicode locale makes all conversions superfluous which eliminates the 7577 risk of conversion errors. It also eliminates potentially wrong 7578 expectations about the character set between NeoMutt and external 7579 programs. 7580 </para> 7581 <para> 7582 The terminal emulator used also must be properly configured for the 7583 current locale. Terminal emulators usually do <emphasis>not</emphasis> 7584 derive the locale from environment variables, they need to be 7585 configured separately. If the terminal is incorrectly configured, 7586 NeoMutt may display random and unexpected characters (question marks, 7587 octal codes, or just random glyphs), format strings may not work as 7588 expected, you may not be abled to enter non-ascii characters, and 7589 possible more. Data is always represented using bytes and so a correct 7590 setup is very important as to the machine, all character sets 7591 <quote>look</quote> the same. 7592 </para> 7593 <para> 7594 Warning: A mismatch between what system and library functions think the 7595 locale is and what NeoMutt was told what the locale is may make it 7596 behave badly with non-ascii input: it will fail at seemingly random 7597 places. This warning is to be taken seriously since not only local mail 7598 handling may suffer: sent messages may carry wrong character set 7599 information the <emphasis>receiver</emphasis> has too deal with. The 7600 need to set <literal>$charset</literal> directly in most cases points 7601 at terminal and environment variable setup problems, not NeoMutt 7602 problems. 7603 </para> 7604 <para> 7605 A list of officially assigned and known character sets can be found at 7606 <ulink url="http://www.iana.org/assignments/character-sets">IANA</ulink>, 7607 a list of locally supported locales can be obtained by running 7608 <literal>locale -a</literal>. 7609 </para> 7610 </sect1> 7611 7612 <sect1 id="regex"> 7613 <title>Regular Expressions</title> 7614 <para> 7615 All string patterns in NeoMutt including those in more complex 7616 <link linkend="patterns">patterns</link> must be specified using 7617 regular expressions (regex) in the <quote>POSIX extended</quote> syntax 7618 (which is more or less the syntax used by egrep and GNU awk). For your 7619 convenience, we have included below a brief description of this syntax. 7620 </para> 7621 <para> 7622 The search is case sensitive if the pattern contains at least one upper 7623 case letter, and case insensitive otherwise. 7624 </para> 7625 <note> 7626 <para> 7627 <quote>\</quote> must be quoted if used for a regular expression in 7628 an initialization command: <quote>\\</quote>. 7629 </para> 7630 </note> 7631 <para> 7632 A regular expression is a pattern that describes a set of strings. 7633 Regular expressions are constructed analogously to arithmetic 7634 expressions, by using various operators to combine smaller expressions. 7635 </para> 7636 <note> 7637 <para> 7638 The regular expression can be enclosed/delimited by either " or 7639 ' which is useful if the regular expression includes a white-space 7640 character. See <xref linkend="neomuttrc-syntax" /> for more 7641 information on " and ' delimiter processing. To match a literal " or 7642 ' you must preface it with \ (backslash). 7643 </para> 7644 </note> 7645 <para> 7646 The fundamental building blocks are the regular expressions that match 7647 a single character. Most characters, including all letters and digits, 7648 are regular expressions that match themselves. Any metacharacter with 7649 special meaning may be quoted by preceding it with a backslash. 7650 </para> 7651 <para> 7652 The period <quote>.</quote> matches any single character. The caret 7653 <quote>^</quote> and the dollar sign <quote>$</quote> are 7654 metacharacters that respectively match the empty string at the 7655 beginning and end of a line. 7656 </para> 7657 <para> 7658 A list of characters enclosed by <quote>[</quote> and <quote>]</quote> 7659 matches any single character in that list; if the first character of 7660 the list is a caret <quote>^</quote> then it matches any character 7661 <emphasis>not</emphasis> in the list. For example, the regular 7662 expression <emphasis>[0123456789]</emphasis> matches any single digit. 7663 A range of ASCII characters may be specified by giving the first and 7664 last characters, separated by a hyphen <quote>-</quote>. Most 7665 metacharacters lose their special meaning inside lists. To include 7666 a literal <quote>]</quote> place it first in the list. Similarly, to 7667 include a literal <quote>^</quote> place it anywhere but first. 7668 Finally, to include a literal hyphen <quote>-</quote> place it last. 7669 </para> 7670 <para> 7671 Certain named classes of characters are predefined. Character classes 7672 consist of <quote>[:</quote>, a keyword denoting the class, and 7673 <quote>:]</quote>. The following classes are defined by the POSIX 7674 standard in <xref linkend="posix-regex-char-classes" /> 7675 </para> 7676 7677 <table id="posix-regex-char-classes"> 7678 <title>POSIX regular expression character classes</title> 7679 <tgroup cols="2"> 7680 <thead> 7681 <row> 7682 <entry>Character class</entry> 7683 <entry>Description</entry> 7684 </row> 7685 </thead> 7686 <tbody> 7687 <row> 7688 <entry>[:alnum:]</entry> 7689 <entry> 7690 Alphanumeric characters 7691 </entry> 7692 </row> 7693 <row> 7694 <entry>[:alpha:]</entry> 7695 <entry> 7696 Alphabetic characters 7697 </entry> 7698 </row> 7699 <row> 7700 <entry>[:blank:]</entry> 7701 <entry> 7702 Space or tab characters 7703 </entry> 7704 </row> 7705 <row> 7706 <entry>[:cntrl:]</entry> 7707 <entry> 7708 Control characters 7709 </entry> 7710 </row> 7711 <row> 7712 <entry>[:digit:]</entry> 7713 <entry> 7714 Numeric characters 7715 </entry> 7716 </row> 7717 <row> 7718 <entry>[:graph:]</entry> 7719 <entry> 7720 Characters that are both printable and visible. (A space is 7721 printable, but not visible, while an <quote>a</quote> is both) 7722 </entry> 7723 </row> 7724 <row> 7725 <entry>[:lower:]</entry> 7726 <entry> 7727 Lower-case alphabetic characters 7728 </entry> 7729 </row> 7730 <row> 7731 <entry>[:print:]</entry> 7732 <entry> 7733 Printable characters (characters that are not control 7734 characters) 7735 </entry> 7736 </row> 7737 <row> 7738 <entry>[:punct:]</entry> 7739 <entry> 7740 Punctuation characters (characters that are not letter, digits, 7741 control characters, or space characters) 7742 </entry> 7743 </row> 7744 <row> 7745 <entry>[:space:]</entry> 7746 <entry> 7747 Space characters (such as space, tab and formfeed, to name 7748 a few) 7749 </entry> 7750 </row> 7751 <row> 7752 <entry>[:upper:]</entry> 7753 <entry> 7754 Upper-case alphabetic characters 7755 </entry> 7756 </row> 7757 <row> 7758 <entry>[:xdigit:]</entry> 7759 <entry> 7760 Characters that are hexadecimal digits 7761 </entry> 7762 </row> 7763 </tbody> 7764 </tgroup> 7765 </table> 7766 <para> 7767 A character class is only valid in a regular expression inside the 7768 brackets of a character list. 7769 </para> 7770 <note> 7771 <para> 7772 Note that the brackets in these class names are part of the symbolic 7773 names, and must be included in addition to the brackets delimiting 7774 the bracket list. For example, <emphasis>[[:digit:]]</emphasis> is 7775 equivalent to <emphasis>[0-9]</emphasis>. 7776 </para> 7777 </note> 7778 <para> 7779 Two additional special sequences can appear in character lists. These 7780 apply to non-ASCII character sets, which can have single symbols 7781 (called collating elements) that are represented with more than one 7782 character, as well as several characters that are equivalent for 7783 collating or sorting purposes: 7784 </para> 7785 <variablelist> 7786 <varlistentry> 7787 <term>Collating Symbols</term> 7788 <listitem> 7789 <para> 7790 A collating symbol is a multi-character collating element 7791 enclosed in <quote>[.</quote> and <quote>.]</quote>. For example, 7792 if <quote>ch</quote> is a collating element, then 7793 <emphasis>[[.ch.]]</emphasis> is a regex that matches this 7794 collating element, while <emphasis>[ch]</emphasis> is a regex 7795 that matches either <quote>c</quote> or <quote>h</quote>. 7796 </para> 7797 </listitem> 7798 </varlistentry> 7799 <varlistentry> 7800 <term>Equivalence Classes</term> 7801 <listitem> 7802 <para> 7803 An equivalence class is a locale-specific name for a list of 7804 characters that are equivalent. The name is enclosed in 7805 <quote>[=</quote> and <quote>=]</quote>. For example, the name 7806 <quote>e</quote> might be used to represent all of 7807 <quote>e</quote> with grave (<quote>è</quote>), <quote>e</quote> 7808 with acute (<quote>é</quote>) and <quote>e</quote>. In this 7809 case, <emphasis>[[=e=]]</emphasis> is a regex that matches any 7810 of: <quote>e</quote> with grave (<quote>è</quote>), 7811 <quote>e</quote> with acute (<quote>é</quote>) and 7812 <quote>e</quote>. 7813 </para> 7814 </listitem> 7815 </varlistentry> 7816 </variablelist> 7817 <para> 7818 A regular expression matching a single character may be followed by one 7819 of several repetition operators described in 7820 <xref linkend="regex-repeat" />. 7821 </para> 7822 7823 <table id="regex-repeat"> 7824 <title>Regular expression repetition operators</title> 7825 <tgroup cols="2"> 7826 <thead> 7827 <row> 7828 <entry>Operator</entry> 7829 <entry>Description</entry> 7830 </row> 7831 </thead> 7832 <tbody> 7833 <row> 7834 <entry>?</entry> 7835 <entry> 7836 The preceding item is optional and matched at most once 7837 </entry> 7838 </row> 7839 <row> 7840 <entry>*</entry> 7841 <entry> 7842 The preceding item will be matched zero or more times 7843 </entry> 7844 </row> 7845 <row> 7846 <entry>+</entry> 7847 <entry> 7848 The preceding item will be matched one or more times 7849 </entry> 7850 </row> 7851 <row> 7852 <entry>{n}</entry> 7853 <entry> 7854 The preceding item is matched exactly <emphasis>n</emphasis> 7855 times 7856 </entry> 7857 </row> 7858 <row> 7859 <entry>{n,}</entry> 7860 <entry> 7861 The preceding item is matched <emphasis>n</emphasis> or more 7862 times 7863 </entry> 7864 </row> 7865 <row> 7866 <entry>{,m}</entry> 7867 <entry> 7868 The preceding item is matched at most <emphasis>m</emphasis> 7869 times 7870 </entry> 7871 </row> 7872 <row> 7873 <entry>{n,m}</entry> 7874 <entry> 7875 The preceding item is matched at least <emphasis>n</emphasis> 7876 times, but no more than <emphasis>m</emphasis> times 7877 </entry> 7878 </row> 7879 </tbody> 7880 </tgroup> 7881 </table> 7882 <para> 7883 Two regular expressions may be concatenated; the resulting regular 7884 expression matches any string formed by concatenating two substrings 7885 that respectively match the concatenated subexpressions. 7886 </para> 7887 <para> 7888 Two regular expressions may be joined by the infix operator 7889 <quote>|</quote>; the resulting regular expression matches any string 7890 matching either subexpression. 7891 </para> 7892 <para> 7893 Repetition takes precedence over concatenation, which in turn takes 7894 precedence over alternation. A whole subexpression may be enclosed in 7895 parentheses to override these precedence rules. 7896 </para> 7897 <note> 7898 <para> 7899 If you compile NeoMutt with the included regular expression engine, 7900 the following operators may also be used in regular expressions as 7901 described in <xref linkend="regex-gnu-ext" />. 7902 </para> 7903 </note> 7904 7905 <table id="regex-gnu-ext"> 7906 <title>GNU regular expression extensions</title> 7907 <tgroup cols="2"> 7908 <thead> 7909 <row> 7910 <entry>Expression</entry> 7911 <entry>Description</entry> 7912 </row> 7913 </thead> 7914 <tbody> 7915 <row> 7916 <entry>\y</entry> 7917 <entry> 7918 Matches the empty string at either the beginning or the end of 7919 a word 7920 </entry> 7921 </row> 7922 <row> 7923 <entry>\B</entry> 7924 <entry> 7925 Matches the empty string within a word 7926 </entry> 7927 </row> 7928 <row> 7929 <entry>\<</entry> 7930 <entry> 7931 Matches the empty string at the beginning of a word 7932 </entry> 7933 </row> 7934 <row> 7935 <entry>\></entry> 7936 <entry> 7937 Matches the empty string at the end of a word 7938 </entry> 7939 </row> 7940 <row> 7941 <entry>\w</entry> 7942 <entry> 7943 Matches any word-constituent character (letter, digit, or 7944 underscore) 7945 </entry> 7946 </row> 7947 <row> 7948 <entry>\W</entry> 7949 <entry> 7950 Matches any character that is not word-constituent 7951 </entry> 7952 </row> 7953 <row> 7954 <entry>\`</entry> 7955 <entry> 7956 Matches the empty string at the beginning of a buffer (string) 7957 </entry> 7958 </row> 7959 <row> 7960 <entry>\'</entry> 7961 <entry> 7962 Matches the empty string at the end of a buffer 7963 </entry> 7964 </row> 7965 </tbody> 7966 </tgroup> 7967 </table> 7968 <para> 7969 Please note however that these operators are not defined by POSIX, so 7970 they may or may not be available in stock libraries on various systems. 7971 </para> 7972 </sect1> 7973 7974 <sect1 id="patterns"> 7975 <title>Patterns: Searching, Limiting and Tagging</title> 7976 7977 <sect2 id="patterns-modifier"> 7978 <title>Pattern Modifier</title> 7979 <para> 7980 Many of NeoMutt's commands allow you to specify a pattern to match 7981 (<literal>limit</literal>, <literal>tag-pattern</literal>, 7982 <literal>delete-pattern</literal>, etc.). 7983 <xref linkend="tab-patterns" /> shows several ways to select 7984 messages while <xref linkend="tab-patterns-alias" /> shows ways of selecting aliases. 7985 </para> 7986 7987 <table id="tab-patterns"> 7988 <title>Pattern modifiers</title> 7989 <tgroup cols="3"> 7990 <thead> 7991 <row> 7992 <entry>Pattern modifier</entry> 7993 <entry>Notes</entry> 7994 <entry>Description</entry> 7995 </row> 7996 </thead> 7997 <tbody> 7998 <row> 7999 <entry>~A</entry> 8000 <entry></entry> 8001 <entry> 8002 all messages 8003 </entry> 8004 </row> 8005 <row> 8006 <entry>~b <emphasis>EXPR</emphasis></entry> 8007 <entry>d)</entry> 8008 <entry> 8009 messages which contain <emphasis>EXPR</emphasis> in the 8010 message body 8011 </entry> 8012 </row> 8013 <row> 8014 <entry>=b <emphasis>STRING</emphasis></entry> 8015 <entry></entry> 8016 <entry> 8017 If IMAP is enabled, like ~b but searches for 8018 <emphasis>STRING</emphasis> on the server, rather than 8019 downloading each message and searching it locally. 8020 </entry> 8021 </row> 8022 <row> 8023 <entry>~B <emphasis>EXPR</emphasis></entry> 8024 <entry>d)</entry> 8025 <entry> 8026 messages which contain <emphasis>EXPR</emphasis>in the whole 8027 message 8028 </entry> 8029 </row> 8030 <row> 8031 <entry>=B <emphasis>STRING</emphasis></entry> 8032 <entry></entry> 8033 <entry> 8034 If IMAP is enabled, like ~B but searches for 8035 <emphasis>STRING</emphasis>on the server, rather than 8036 downloading each message and searching it locally. 8037 </entry> 8038 </row> 8039 <row> 8040 <entry>~c <emphasis>EXPR</emphasis></entry> 8041 <entry></entry> 8042 <entry> 8043 messages carbon-copied to <emphasis>EXPR</emphasis> 8044 </entry> 8045 </row> 8046 <row> 8047 <entry>%c <emphasis>GROUP</emphasis></entry> 8048 <entry></entry> 8049 <entry> 8050 messages carbon-copied to any member of 8051 <emphasis>GROUP</emphasis> 8052 </entry> 8053 </row> 8054 <row> 8055 <entry>~C <emphasis>EXPR</emphasis></entry> 8056 <entry></entry> 8057 <entry> 8058 messages either to: or cc: <emphasis>EXPR</emphasis> 8059 </entry> 8060 </row> 8061 <row> 8062 <entry>%C <emphasis>GROUP</emphasis></entry> 8063 <entry></entry> 8064 <entry> 8065 messages either to: or cc: to any member of 8066 <emphasis>GROUP</emphasis> 8067 </entry> 8068 </row> 8069 <row> 8070 <entry>~d [<emphasis>MIN</emphasis>]-[<emphasis>MAX</emphasis>]</entry> 8071 <entry></entry> 8072 <entry> 8073 messages with <quote>date-sent</quote> in a Date range 8074 </entry> 8075 </row> 8076 <row> 8077 <entry>~D</entry> 8078 <entry></entry> 8079 <entry> 8080 deleted messages 8081 </entry> 8082 </row> 8083 <row> 8084 <entry>~e <emphasis>EXPR</emphasis></entry> 8085 <entry></entry> 8086 <entry> 8087 messages which contains <emphasis>EXPR</emphasis> in the 8088 <quote>Sender</quote> field 8089 </entry> 8090 </row> 8091 <row> 8092 <entry>%e <emphasis>GROUP</emphasis></entry> 8093 <entry></entry> 8094 <entry> 8095 messages which contain a member of <emphasis>GROUP</emphasis> 8096 in the <quote>Sender</quote> field 8097 </entry> 8098 </row> 8099 <row> 8100 <entry>~E</entry> 8101 <entry></entry> 8102 <entry> 8103 expired messages 8104 </entry> 8105 </row> 8106 <row> 8107 <entry>~F</entry> 8108 <entry></entry> 8109 <entry> 8110 flagged messages 8111 </entry> 8112 </row> 8113 <row> 8114 <entry>~f <emphasis>EXPR</emphasis></entry> 8115 <entry></entry> 8116 <entry> 8117 messages originating from <emphasis>EXPR</emphasis> 8118 </entry> 8119 </row> 8120 <row> 8121 <entry>%f <emphasis>GROUP</emphasis></entry> 8122 <entry></entry> 8123 <entry> 8124 messages originating from any member of 8125 <emphasis>GROUP</emphasis> 8126 </entry> 8127 </row> 8128 <row> 8129 <entry>~g</entry> 8130 <entry></entry> 8131 <entry> 8132 cryptographically signed messages 8133 </entry> 8134 </row> 8135 <row> 8136 <entry>~G</entry> 8137 <entry></entry> 8138 <entry> 8139 cryptographically encrypted messages 8140 </entry> 8141 </row> 8142 <row> 8143 <entry>~h <emphasis>EXPR</emphasis></entry> 8144 <entry>d)</entry> 8145 <entry> 8146 messages which contain <emphasis>EXPR</emphasis>in the 8147 message header 8148 </entry> 8149 </row> 8150 <row> 8151 <entry>=h <emphasis>STRING</emphasis></entry> 8152 <entry></entry> 8153 <entry> 8154 If IMAP is enabled, like ~h but searches for 8155 <emphasis>STRING</emphasis>on the server, rather than 8156 downloading each message and searching it locally; 8157 <emphasis>STRING</emphasis>must be of the form 8158 <quote>header: substring</quote>(see below). 8159 </entry> 8160 </row> 8161 <row> 8162 <entry>~H <emphasis>EXPR</emphasis></entry> 8163 <entry></entry> 8164 <entry> 8165 messages with a spam attribute matching 8166 <emphasis>EXPR</emphasis> 8167 </entry> 8168 </row> 8169 <row> 8170 <entry>~i <emphasis>EXPR</emphasis></entry> 8171 <entry></entry> 8172 <entry> 8173 messages which match <emphasis>EXPR</emphasis> in the 8174 <quote>Message-ID</quote> field 8175 </entry> 8176 </row> 8177 <row> 8178 <entry>~I <emphasis>QUERY</emphasis></entry> 8179 <entry></entry> 8180 <entry> 8181 messages whose <quote>Message-ID</quote> field is included in 8182 the results returned from an external search program, when the program 8183 is run with <emphasis>QUERY</emphasis> as its argument. 8184 This is explained in greater detail in the variable reference entry 8185 <xref linkend="external-search-command"/>, 8186 </entry> 8187 </row> 8188 <row> 8189 <entry>~k</entry> 8190 <entry></entry> 8191 <entry> 8192 messages which contain PGP key material 8193 </entry> 8194 </row> 8195 <row> 8196 <entry>~L <emphasis>EXPR</emphasis></entry> 8197 <entry></entry> 8198 <entry> 8199 messages either originated or received by 8200 <emphasis>EXPR</emphasis> 8201 </entry> 8202 </row> 8203 <row> 8204 <entry>%L <emphasis>GROUP</emphasis></entry> 8205 <entry></entry> 8206 <entry> 8207 message either originated or received by any member of 8208 <emphasis>GROUP</emphasis> 8209 </entry> 8210 </row> 8211 <row> 8212 <entry>~l</entry> 8213 <entry></entry> 8214 <entry> 8215 messages addressed to a known mailing list 8216 </entry> 8217 </row> 8218 <row> 8219 <entry>~m [<emphasis>MIN</emphasis>]-[<emphasis>MAX</emphasis>]</entry> 8220 <entry>c)</entry> 8221 <entry> 8222 messages with numbers in the range <emphasis>MIN</emphasis> 8223 to <emphasis>MAX</emphasis> 8224 </entry> 8225 </row> 8226 <row> 8227 <entry>~m <[<emphasis>MAX</emphasis>]</entry> 8228 <entry>c)</entry> 8229 <entry> 8230 messages with numbers less than <emphasis>MAX</emphasis> 8231 </entry> 8232 </row> 8233 <row> 8234 <entry>~m >[<emphasis>MIN</emphasis>]</entry> 8235 <entry>c)</entry> 8236 <entry> 8237 messages with numbers greater than <emphasis>MIN</emphasis> 8238 </entry> 8239 </row> 8240 <row> 8241 <entry>~m [<emphasis>M</emphasis>]</entry> 8242 <entry>c)</entry> 8243 <entry> 8244 just message number <emphasis>M</emphasis> 8245 </entry> 8246 </row> 8247 <row> 8248 <entry>~m [<emphasis>MIN</emphasis>],[<emphasis>MAX</emphasis>]</entry> 8249 <entry>c)</entry> 8250 <entry> 8251 messages with offsets (from selected message) in the range 8252 <emphasis>MIN</emphasis> to <emphasis>MAX</emphasis> 8253 </entry> 8254 </row> 8255 <row> 8256 <entry>~M <emphasis>EXPR</emphasis></entry> 8257 <entry>d)</entry> 8258 <entry> 8259 messages which contain a mime Content-Type matching 8260 <emphasis>EXPR</emphasis> 8261 </entry> 8262 </row> 8263 <row> 8264 <entry>~n [<emphasis>MIN</emphasis>]-[<emphasis>MAX</emphasis>]</entry> 8265 <entry>a)</entry> 8266 <entry> 8267 messages with a score in the range <emphasis>MIN</emphasis> 8268 to <emphasis>MAX</emphasis> 8269 </entry> 8270 </row> 8271 <row> 8272 <entry>~N</entry> 8273 <entry></entry> 8274 <entry> 8275 new messages 8276 </entry> 8277 </row> 8278 <row> 8279 <entry>~O</entry> 8280 <entry></entry> 8281 <entry> 8282 old messages 8283 </entry> 8284 </row> 8285 <row> 8286 <entry>~p</entry> 8287 <entry></entry> 8288 <entry> 8289 messages addressed to you (consults <link linkend="from">$from</link>, 8290 <command>alternates</command>, and local account/hostname information) 8291 </entry> 8292 </row> 8293 <row> 8294 <entry>~P</entry> 8295 <entry></entry> 8296 <entry> 8297 messages from you (consults <link linkend="from">$from</link>, 8298 <command>alternates</command>, and local account/hostname information) 8299 </entry> 8300 </row> 8301 <row> 8302 <entry>~Q</entry> 8303 <entry></entry> 8304 <entry> 8305 messages which have been replied to 8306 </entry> 8307 </row> 8308 <row> 8309 <entry>~r [<emphasis>MIN</emphasis>]-[<emphasis>MAX</emphasis>]</entry> 8310 <entry></entry> 8311 <entry> 8312 messages with <quote>date-received</quote> in a Date range 8313 </entry> 8314 </row> 8315 <row> 8316 <entry>~R</entry> 8317 <entry></entry> 8318 <entry> 8319 read messages 8320 </entry> 8321 </row> 8322 <row> 8323 <entry>~s <emphasis>EXPR</emphasis></entry> 8324 <entry></entry> 8325 <entry> 8326 messages having <emphasis>EXPR</emphasis> in the 8327 <quote>Subject</quote> field. 8328 </entry> 8329 </row> 8330 <row> 8331 <entry>~S</entry> 8332 <entry></entry> 8333 <entry> 8334 superseded messages 8335 </entry> 8336 </row> 8337 <row> 8338 <entry>~t <emphasis>EXPR</emphasis></entry> 8339 <entry></entry> 8340 <entry> 8341 messages addressed to <emphasis>EXPR</emphasis> 8342 </entry> 8343 </row> 8344 <row> 8345 <entry>~T</entry> 8346 <entry></entry> 8347 <entry> 8348 tagged messages 8349 </entry> 8350 </row> 8351 <row> 8352 <entry>~u</entry> 8353 <entry></entry> 8354 <entry> 8355 messages addressed to a subscribed mailing list 8356 </entry> 8357 </row> 8358 <row> 8359 <entry>~U</entry> 8360 <entry></entry> 8361 <entry> 8362 unread messages 8363 </entry> 8364 </row> 8365 <row> 8366 <entry>~v</entry> 8367 <entry></entry> 8368 <entry> 8369 messages part of a collapsed thread. 8370 </entry> 8371 </row> 8372 <row> 8373 <entry>~V</entry> 8374 <entry></entry> 8375 <entry> 8376 cryptographically verified messages 8377 </entry> 8378 </row> 8379 <row> 8380 <entry>~w <emphasis>EXPR</emphasis></entry> 8381 <entry></entry> 8382 <entry> 8383 newsgroups matching EXPR 8384 </entry> 8385 </row> 8386 <row> 8387 <entry>~x <emphasis>EXPR</emphasis></entry> 8388 <entry></entry> 8389 <entry> 8390 messages which contain <emphasis>EXPR</emphasis> in the 8391 <quote>References</quote> or <quote>In-Reply-To</quote> field 8392 </entry> 8393 </row> 8394 <row> 8395 <entry>~X [<emphasis>MIN</emphasis>]-[<emphasis>MAX</emphasis>]</entry> 8396 <entry>a), d)</entry> 8397 <entry> 8398 messages with <emphasis>MIN</emphasis> to <emphasis>MAX</emphasis> attachments 8399 </entry> 8400 </row> 8401 <row> 8402 <entry>~y <emphasis>EXPR</emphasis></entry> 8403 <entry></entry> 8404 <entry> 8405 messages which contain <emphasis>EXPR</emphasis> in their 8406 keywords 8407 </entry> 8408 </row> 8409 <row> 8410 <entry>~Y <emphasis>EXPR</emphasis></entry> 8411 <entry></entry> 8412 <entry> 8413 messages whose tags match <emphasis>EXPR</emphasis> 8414 </entry> 8415 </row> 8416 <row> 8417 <entry>~z [<emphasis>MIN</emphasis>]-[<emphasis>MAX</emphasis>]</entry> 8418 <entry>a), b)</entry> 8419 <entry> 8420 messages with a size in the range <emphasis>MIN</emphasis> to 8421 <emphasis>MAX</emphasis> 8422 </entry> 8423 </row> 8424 <row> 8425 <entry>=/ <emphasis>STRING</emphasis></entry> 8426 <entry></entry> 8427 <entry> 8428 IMAP custom server-side search for 8429 <emphasis>STRING</emphasis>. Currently only defined for 8430 Gmail. See: 8431 <link linkend="gmail-patterns">Gmail Patterns</link> 8432 </entry> 8433 </row> 8434 <row> 8435 <entry>~=</entry> 8436 <entry></entry> 8437 <entry> 8438 duplicated messages (see 8439 <link linkend="duplicate-threads">$duplicate_threads</link>) 8440 </entry> 8441 </row> 8442 <row> 8443 <entry>~#</entry> 8444 <entry></entry> 8445 <entry> 8446 broken threads (see 8447 <link linkend="strict-threads">$strict_threads</link>) 8448 </entry> 8449 </row> 8450 <row> 8451 <entry>~$</entry> 8452 <entry></entry> 8453 <entry> 8454 unreferenced messages (requires threaded view) 8455 </entry> 8456 </row> 8457 <row> 8458 <entry>~(<emphasis>PATTERN</emphasis>)</entry> 8459 <entry></entry> 8460 <entry> 8461 messages in threads containing messages matching 8462 <emphasis>PATTERN</emphasis>, e.g. all threads containing 8463 messages from you: ~(~P) 8464 </entry> 8465 </row> 8466 <row> 8467 <entry>~<(<emphasis>PATTERN</emphasis>)</entry> 8468 <entry></entry> 8469 <entry> 8470 messages whose immediate parent matches 8471 <emphasis>PATTERN</emphasis>, e.g. replies to your messages: 8472 ~<(~P) 8473 </entry> 8474 </row> 8475 <row> 8476 <entry>~>(<emphasis>PATTERN</emphasis>)</entry> 8477 <entry></entry> 8478 <entry> 8479 messages having an immediate child matching 8480 <emphasis>PATTERN</emphasis>, e.g. messages you replied to: 8481 ~>(~P) 8482 </entry> 8483 </row> 8484 </tbody> 8485 </tgroup> 8486 </table> 8487 8488 <table id="tab-patterns-alias"> 8489 <title>Alias pattern modifiers</title> 8490 <tgroup cols="3"> 8491 <thead> 8492 <row> 8493 <entry>Pattern modifier</entry> 8494 <entry>Notes</entry> 8495 <entry>Description</entry> 8496 </row> 8497 </thead> 8498 <tbody> 8499 <row> 8500 <entry>~c <emphasis>EXPR</emphasis></entry> 8501 <entry></entry> 8502 <entry> 8503 aliases which contain <emphasis>EXPR</emphasis> in the 8504 alias comment 8505 </entry> 8506 </row> 8507 <row> 8508 <entry>~f <emphasis>EXPR</emphasis></entry> 8509 <entry></entry> 8510 <entry> 8511 aliases which contain <emphasis>EXPR</emphasis> in the 8512 alias name (<emphasis>From</emphasis> part of alias) 8513 </entry> 8514 </row> 8515 <row> 8516 <entry>~t <emphasis>EXPR</emphasis></entry> 8517 <entry></entry> 8518 <entry> 8519 aliases which contain <emphasis>EXPR</emphasis> in the 8520 alias address (<emphasis>To</emphasis> part of alias) 8521 </entry> 8522 </row> 8523 </tbody> 8524 </tgroup> 8525 </table> 8526 8527 <para> 8528 Where <emphasis>EXPR</emphasis> is a 8529 <link linkend="regex">regular expression</link>, and 8530 <emphasis>GROUP</emphasis> is an 8531 <link linkend="addrgroup">address group</link>. 8532 </para> 8533 <para> 8534 a) The forms <quote><[<emphasis>MAX</emphasis>]</quote>, 8535 <quote>>[<emphasis>MIN</emphasis>]</quote>, 8536 <quote>[<emphasis>MIN</emphasis>]-</quote> and 8537 <quote>-[<emphasis>MAX</emphasis>]</quote> are allowed, too. 8538 </para> 8539 <para> 8540 b) The suffixes <quote>K</quote> and <quote>M</quote> are allowed to 8541 specify kilobyte and megabyte respectively. 8542 </para> 8543 <para> 8544 c) The message number ranges (introduced by <literal>~m</literal>) 8545 are even more general and powerful than the other types of ranges. 8546 Read on and see <xref linkend="message-ranges" /> below. 8547 </para> 8548 <para> 8549 d) These patterns read each message in, and can therefore be much 8550 slower. Over IMAP this will entail downloading each message. They 8551 can not be used for <link linkend="score-command">message scoring</link>, 8552 and it is recommended to avoid using them for index coloring. 8553 </para> 8554 <para> 8555 Special attention has to be paid when using regular expressions 8556 inside of patterns. Specifically, NeoMutt's parser for these patterns 8557 will strip one level of backslash (<quote>\</quote>), which is 8558 normally used for quoting. If it is your intention to use a backslash 8559 in the regular expression, you will need to use two backslashes 8560 instead (<quote>\\</quote>). 8561 </para> 8562 <para> 8563 You can force NeoMutt to treat 8564 <emphasis>EXPR</emphasis> as a simple substring instead of a regular 8565 expression by using = instead of ~ in the pattern name. For example, 8566 <literal>=b *.*</literal> will find all messages that contain the 8567 literal string <quote>*.*</quote>. Simple string matches are less 8568 powerful than regular expressions but can be considerably faster. 8569 </para> 8570 <para> 8571 For IMAP folders, string matches <literal>=b</literal>, 8572 <literal>=B</literal>, and <literal>=h</literal> will be performed on 8573 the server instead of by fetching every message. IMAP treats 8574 <literal>=h</literal> specially: it must be of the form 8575 <quote>header: substring</quote> and will not partially match header 8576 names. The substring part may be omitted if you simply wish to find 8577 messages containing a particular header without regard to its value. 8578 </para> 8579 <para> 8580 Patterns matching lists of addresses (notably c, C, p, P and t) match 8581 if there is at least one match in the whole list. If you want to make 8582 sure that all elements of that list match, you need to prefix your 8583 pattern with <quote>^</quote>. This example matches all mails which 8584 only has recipients from Germany. 8585 </para> 8586 <example id="ex-recips"> 8587 <title>Matching all addresses in address lists</title> 8588 <screen>^~C \.de$</screen> 8589 </example> 8590 <para> 8591 You can restrict address pattern matching to aliases that you have 8592 defined with the "@" modifier. This example matches messages whose 8593 recipients are all from Germany, and who are known to your alias 8594 list. 8595 </para> 8596 <example id="ex-restrict-to-aliases"> 8597 <title>Matching restricted to aliases</title> 8598 <screen>^@~C \.de$</screen> 8599 </example> 8600 <para> 8601 To match any defined alias, use a regular expression that matches any 8602 string. This example matches messages whose senders are known 8603 aliases. 8604 </para> 8605 <example id="ex-match-alias"> 8606 <title>Matching any defined alias</title> 8607 <screen>@~f .</screen> 8608 </example> 8609 8610 <sect3 id="message-ranges"> 8611 <title>Message Ranges</title> 8612 <para> 8613 If a message number range (from now on: MNR) contains a comma 8614 (<literal>,</literal>), it is a <emphasis>relative</emphasis> MNR. 8615 That means the numbers denote <emphasis>offsets</emphasis> from the 8616 highlighted message. For example: 8617 </para> 8618 8619 <table id="relative-mnrs"> 8620 <title>Relative Message Number Ranges</title> 8621 <tgroup cols="2"> 8622 <thead> 8623 <row> 8624 <entry>Pattern</entry> 8625 <entry>Explanation</entry> 8626 </row> 8627 </thead> 8628 <tbody> 8629 <row> 8630 <entry> 8631 <literal>~m -2,2</literal> 8632 </entry> 8633 <entry>Previous 2, highlighted and next 2 emails</entry> 8634 </row> 8635 <row> 8636 <entry> 8637 <literal>~m 0,1</literal> 8638 </entry> 8639 <entry>Highlighted and next email</entry> 8640 </row> 8641 </tbody> 8642 </tgroup> 8643 </table> 8644 <para> 8645 In addition to numbers, either side of the range can also contain 8646 one of the special characters (shortcuts) <literal>.^$</literal>. 8647 The meaning is: 8648 </para> 8649 8650 <table id="mnrs-shortcuts"> 8651 <title>Message Number Shortcuts</title> 8652 <tgroup cols="4"> 8653 <thead> 8654 <row> 8655 <entry>Shortcut</entry> 8656 <entry>Explanation</entry> 8657 <entry>Example</entry> 8658 <entry>Meaning</entry> 8659 </row> 8660 </thead> 8661 <tbody> 8662 <row> 8663 <entry><literal>.</literal></entry> 8664 <entry>Current / Highlighted</entry> 8665 <entry><literal>~m -3,.</literal></entry> 8666 <entry>Previous 3 emails plus the highlighted one</entry> 8667 </row> 8668 <row> 8669 <entry><literal>$</literal></entry> 8670 <entry>Last</entry> 8671 <entry><literal>~m .,$</literal></entry> 8672 <entry>Highlighted email and all the later ones</entry> 8673 </row> 8674 <row> 8675 <entry><literal>^</literal></entry> 8676 <entry>First</entry> 8677 <entry><literal>~m ^,1</literal></entry> 8678 <entry>Highlighted, next and all preceding ones</entry> 8679 </row> 8680 </tbody> 8681 </tgroup> 8682 </table> 8683 <para> 8684 Lastly, you can also leave either side of the range blank, to make 8685 it extend as far as possible. For example, <literal>~m ,1</literal> 8686 has the same meaning as the last example in 8687 <xref linkend="mnrs-shortcuts" />. 8688 </para> 8689 <para> 8690 Otherwise, if a MNR <emphasis>doesn't</emphasis> contain a comma, 8691 the meaning is similar to other ranges, except that the shortcuts 8692 are still available. Examples: 8693 </para> 8694 8695 <table id="mnrs-absolute"> 8696 <title>Absolute Message Number Ranges</title> 8697 <tgroup cols="2"> 8698 <thead> 8699 <row> 8700 <entry>Pattern</entry> 8701 <entry>Explanation</entry> 8702 </row> 8703 </thead> 8704 <tbody> 8705 <row> 8706 <entry><literal>~m 3-10</literal></entry> 8707 <entry>Emails 3 to 10</entry> 8708 </row> 8709 <row> 8710 <entry><literal>~m -10</literal></entry> 8711 <entry>Emails 1 to 10</entry> 8712 </row> 8713 <row> 8714 <entry><literal>~m 10-</literal></entry> 8715 <entry>Emails 10 to last</entry> 8716 </row> 8717 <row> 8718 <entry><literal>~m <3</literal></entry> 8719 <entry>First and second email</entry> 8720 </row> 8721 <row> 8722 <entry><literal>~m ^-2</literal></entry> 8723 <entry>First and second email</entry> 8724 </row> 8725 <row> 8726 <entry><literal>~m >1</literal></entry> 8727 <entry>Everything but first email</entry> 8728 </row> 8729 <row> 8730 <entry><literal>~m 2-$</literal></entry> 8731 <entry>Everything but first email</entry> 8732 </row> 8733 <row> 8734 <entry><literal>~m 2</literal></entry> 8735 <entry>Just the second email</entry> 8736 </row> 8737 </tbody> 8738 </tgroup> 8739 </table> 8740 </sect3> 8741 </sect2> 8742 8743 <sect2 id="simple-searches"> 8744 <title>Simple Searches</title> 8745 <para> 8746 NeoMutt supports two versions of so called 8747 <quote>simple searches</quote>. These are issued if the query entered 8748 for searching, limiting and similar operations does not seem to 8749 contain a valid pattern modifier (i.e. it does not contain one of 8750 these characters: <quote>~</quote>, <quote>=</quote> or 8751 <quote>%</quote>). If the query is supposed to contain one of these 8752 special characters, they must be escaped by prepending a backslash 8753 (<quote>\</quote>). 8754 </para> 8755 <para> 8756 The first type is by checking whether the query string equals 8757 a keyword case-insensitively from 8758 <xref linkend="tab-simplesearch-keywords" />: If that is the case, 8759 NeoMutt will use the shown pattern modifier instead. If a keyword 8760 would conflict with your search keyword, you need to turn it into 8761 a regular expression to avoid matching the keyword table. For 8762 example, if you want to find all messages matching 8763 <quote>flag</quote> (using 8764 <link linkend="simple-search">$simple_search</link>) but don't want 8765 to match flagged messages, simply search for 8766 <quote><literal>[f]lag</literal></quote>. 8767 </para> 8768 8769 <table id="tab-simplesearch-keywords"> 8770 <title>Simple search keywords</title> 8771 <tgroup cols="2"> 8772 <thead> 8773 <row> 8774 <entry>Keyword</entry> 8775 <entry>Pattern modifier</entry> 8776 </row> 8777 </thead> 8778 <tbody> 8779 <row> 8780 <entry>all</entry> 8781 <entry>~A</entry> 8782 </row> 8783 <row> 8784 <entry>.</entry> 8785 <entry>~A</entry> 8786 </row> 8787 <row> 8788 <entry>^</entry> 8789 <entry>~A</entry> 8790 </row> 8791 <row> 8792 <entry>del</entry> 8793 <entry>~D</entry> 8794 </row> 8795 <row> 8796 <entry>flag</entry> 8797 <entry>~F</entry> 8798 </row> 8799 <row> 8800 <entry>new</entry> 8801 <entry>~N</entry> 8802 </row> 8803 <row> 8804 <entry>old</entry> 8805 <entry>~O</entry> 8806 </row> 8807 <row> 8808 <entry>repl</entry> 8809 <entry>~Q</entry> 8810 </row> 8811 <row> 8812 <entry>read</entry> 8813 <entry>~R</entry> 8814 </row> 8815 <row> 8816 <entry>tag</entry> 8817 <entry>~T</entry> 8818 </row> 8819 <row> 8820 <entry>unread</entry> 8821 <entry>~U</entry> 8822 </row> 8823 </tbody> 8824 </tgroup> 8825 </table> 8826 <para> 8827 The second type of simple search is to build a complex search pattern 8828 using <link linkend="simple-search">$simple_search</link> as 8829 a template. NeoMutt will insert your query properly quoted and search 8830 for the composed complex query. 8831 </para> 8832 </sect2> 8833 8834 <sect2 id="complex-patterns"> 8835 <title>Nesting and Boolean Operators</title> 8836 <para> 8837 Logical AND is performed by specifying more than one criterion. For 8838 example: 8839 </para> 8840 <screen>~t work ~f elkins</screen> 8841 <para> 8842 would select messages which contain the word <quote>work</quote> in 8843 the list of recipients <emphasis>and</emphasis> that have the word 8844 <quote>elkins</quote> in the <quote>From</quote> header field. 8845 </para> 8846 <para> 8847 NeoMutt also recognizes the following operators to create more 8848 complex search patterns: 8849 </para> 8850 <itemizedlist> 8851 <listitem> 8852 <para> 8853 ! – logical NOT operator 8854 </para> 8855 </listitem> 8856 <listitem> 8857 <para> 8858 | – logical OR operator 8859 </para> 8860 </listitem> 8861 <listitem> 8862 <para> 8863 () – logical grouping operator 8864 </para> 8865 </listitem> 8866 </itemizedlist> 8867 <para> 8868 Here is an example illustrating a complex search pattern. This 8869 pattern will select all messages which do not contain 8870 <quote>work</quote> in the <quote>To</quote> or <quote>Cc</quote> 8871 field and which are from <quote>elkins</quote>. 8872 </para> 8873 <example id="ex-pattern-bool"> 8874 <title>Using boolean operators in patterns</title> 8875 <screen>!(~t work|~c work) ~f elkins</screen> 8876 </example> 8877 <para> 8878 Here is an example using white space in the regular expression (note 8879 the <quote>'</quote> and <quote>"</quote> delimiters). For this to 8880 match, the mail's subject must match the 8881 <quote>^Junk +From +Me$</quote> and it must be from either 8882 <quote>Jim +Somebody</quote> or <quote>Ed +SomeoneElse</quote>: 8883 </para> 8884 8885<screen> 8886'~s "^Junk +From +Me$" ~f ("Jim +Somebody"|"Ed +SomeoneElse")' 8887</screen> 8888 8889 <note> 8890 <para> 8891 If a regular expression contains parenthesis, or a vertical bar 8892 ("|"), you <emphasis>must</emphasis> enclose the expression in 8893 double or single quotes since those characters are also used to 8894 separate different parts of NeoMutt's pattern language. For 8895 example: <literal>~f "user@(home\.org|work\.com)"</literal> Without 8896 the quotes, the parenthesis wouldn't end. This would be separated 8897 to two OR'd patterns: <emphasis>~f user@(home\.org</emphasis> and 8898 <emphasis>work\.com)</emphasis>. They are never what you want. 8899 </para> 8900 </note> 8901 </sect2> 8902 8903 <sect2 id="date-patterns"> 8904 <title>Searching by Date</title> 8905 <para> 8906 NeoMutt supports two types of dates, <emphasis>absolute</emphasis> 8907 and <emphasis>relative</emphasis>. 8908 </para> 8909 8910 <sect3 id="date-absolute"> 8911 <title>Absolute Dates</title> 8912 <para> 8913 Dates <emphasis>must</emphasis> be in DD/MM/YY format (month and year 8914 are optional, defaulting to the current month and year) or YYYYMMDD. An 8915 example of a valid range of dates is: 8916 </para> 8917<screen> 8918Limit to messages matching: ~d 20/1/95-31/10 8919Limit to messages matching: ~d 19950120-19951031 8920</screen> 8921 <para> 8922 If you omit the minimum (first) date, and just specify 8923 <quote>-DD/MM/YY</quote> or <quote>-YYYYMMDD</quote>, all messages 8924 <emphasis>before</emphasis> the given date will be selected. If you omit the 8925 maximum(second) date, and specify <quote>DD/MM/YY-</quote>, all messages 8926 <emphasis>after</emphasis> the given date will be selected. If you 8927 specify a single date with no dash (<quote>-</quote>), only 8928 messages sent on the given date will be selected. 8929 </para> 8930 <para> 8931 You can add error margins to absolute dates. An error margin is 8932 a sign (+ or -), followed by a digit, followed by one of the units 8933 in <xref linkend="tab-date-units" />. As a special case, you can 8934 replace the sign by a <quote>*</quote> character, which is 8935 equivalent to giving identical plus and minus error margins. 8936 </para> 8937 8938 <table id="tab-date-units"> 8939 <title>Date units</title> 8940 <tgroup cols="2"> 8941 <thead> 8942 <row> 8943 <entry>Unit</entry> 8944 <entry>Description</entry> 8945 </row> 8946 </thead> 8947 <tbody> 8948 <row> 8949 <entry>y</entry> 8950 <entry>Years</entry> 8951 </row> 8952 <row> 8953 <entry>m</entry> 8954 <entry>Months</entry> 8955 </row> 8956 <row> 8957 <entry>w</entry> 8958 <entry>Weeks</entry> 8959 </row> 8960 <row> 8961 <entry>d</entry> 8962 <entry>Days</entry> 8963 </row> 8964 </tbody> 8965 </tgroup> 8966 </table> 8967 <para> 8968 Example: To select any messages two weeks around January 15, 2001, 8969 you'd use the following pattern: 8970 </para> 8971 <screen>Limit to messages matching: ~d 15/1/2001*2w</screen> 8972 </sect3> 8973 8974 <sect3 id="dates-relative"> 8975 <title>Relative Dates</title> 8976 <para> 8977 This type of date is relative to the current date, and may be 8978 specified as: 8979 </para> 8980 <itemizedlist> 8981 <listitem> 8982 <para> 8983 > <emphasis>offset</emphasis> for messages older than 8984 <emphasis>offset</emphasis> units 8985 </para> 8986 </listitem> 8987 <listitem> 8988 <para> 8989 < <emphasis>offset</emphasis> for messages newer than 8990 <emphasis>offset</emphasis> units 8991 </para> 8992 </listitem> 8993 <listitem> 8994 <para> 8995 = <emphasis>offset</emphasis> for messages exactly 8996 <emphasis>offset</emphasis> units old 8997 </para> 8998 </listitem> 8999 </itemizedlist> 9000 <para> 9001 <emphasis>offset</emphasis> is specified as a positive number with 9002 one of the units from <xref linkend="tab-rel-date-units" />. 9003 </para> 9004 <table id="tab-rel-date-units"> 9005 <title>Relative date units</title> 9006 <tgroup cols="2"> 9007 <thead> 9008 <row> 9009 <entry>Unit</entry> 9010 <entry>Description</entry> 9011 </row> 9012 </thead> 9013 <tbody> 9014 <row> 9015 <entry>y</entry> 9016 <entry>Years</entry> 9017 </row> 9018 <row> 9019 <entry>m</entry> 9020 <entry>Months</entry> 9021 </row> 9022 <row> 9023 <entry>w</entry> 9024 <entry>Weeks</entry> 9025 </row> 9026 <row> 9027 <entry>d</entry> 9028 <entry>Days</entry> 9029 </row> 9030 <row> 9031 <entry>H</entry> 9032 <entry>Hours</entry> 9033 </row> 9034 <row> 9035 <entry>M</entry> 9036 <entry>Minutes</entry> 9037 </row> 9038 <row> 9039 <entry>S</entry> 9040 <entry>Seconds</entry> 9041 </row> 9042 </tbody> 9043 </tgroup> 9044 </table> 9045 <para> 9046 Example: to select messages less than 1 month old, you would use 9047 </para> 9048 <screen>Limit to messages matching: ~d <1m</screen> 9049 <note> 9050 <para> 9051 All dates used when searching are relative to the 9052 <emphasis>local</emphasis> time zone, so unless you change the 9053 setting of your <link linkend="index-format">$index_format</link> 9054 to include a <literal>%[...]</literal> format, these are 9055 <emphasis>not</emphasis> the dates shown in the main index. 9056 </para> 9057 </note> 9058 </sect3> 9059 </sect2> 9060 9061 <sect2 id="gmail-patterns"> 9062 <title>Gmail Patterns</title> 9063 <para> 9064 <literal>=/ "search terms"</literal> invokes server-side search, 9065 passing along the search terms provided. Search results are 9066 constrained by IMAP to be within the current folder. At present this 9067 only supports Gmail's search API IMAP extension. The search language 9068 is entirely up to the mail provider and changes at their discretion. 9069 Using <literal>~/</literal> will silently fail. 9070 </para> 9071 <para> 9072 For up-to-date information about searching, see: 9073 <ulink url="https://support.google.com/mail/answer/7190?hl=en">Gmail's Support Page</ulink>. 9074 You will need to (once) use a web-browser to visit Settings/Labels 9075 and enable "Show in IMAP" for "All Mail". When searching, visit that 9076 folder in NeoMutt to most closely match Gmail search semantics. 9077 </para> 9078 9079 <table id="gmail-example-patterns"> 9080 <title>Gmail Example Patterns</title> 9081 <tgroup cols="2"> 9082 <thead> 9083 <row> 9084 <entry>Pattern</entry> 9085 <entry>Matches</entry> 9086 </row> 9087 </thead> 9088 <tbody> 9089 <row> 9090 <entry> 9091 <literal>=/ "list:foo.example.org has:attachment is:important"</literal> 9092 </entry> 9093 <entry> 9094 the foo.example.org mailing-list per Gmail's definitions, and 9095 has an attachment, and has been marked as important 9096 </entry> 9097 </row> 9098 <row> 9099 <entry> 9100 <literal>=/ "{has:purple-star has:yellow-star} older_than:2m"</literal> 9101 </entry> 9102 <entry> 9103 is older than two months and has either a purple-star or 9104 a yellow-star 9105 </entry> 9106 </row> 9107 </tbody> 9108 </tgroup> 9109 </table> 9110 </sect2> 9111 </sect1> 9112 9113 <sect1 id="markmsg"> 9114 <title>Marking Messages</title> 9115 <para> 9116 There are times that it's useful to ask NeoMutt to "remember" which 9117 message you're currently looking at, while you move elsewhere in your 9118 mailbox. You can do this with the <quote>mark-message</quote> operator, 9119 which is bound to the <quote>~</quote> key by default. Press this key 9120 to enter an identifier for the marked message. When you want to return 9121 to this message, press <quote>'</quote> and the name that you 9122 previously entered. 9123 </para> 9124 <para> 9125 (Message marking is really just a shortcut for defining a macro that 9126 returns you to the current message by searching for its Message-ID. 9127 You can choose a different prefix by setting the 9128 <link linkend="mark-macro-prefix">$mark_macro_prefix</link> variable.) 9129 </para> 9130 </sect1> 9131 9132 <sect1 id="tags"> 9133 <title>Using Tags</title> 9134 <para> 9135 Sometimes it is desirable to perform an operation on a group of 9136 messages all at once rather than one at a time. An example might be to 9137 save messages to a mailing list to a separate folder, or to delete all 9138 messages with a given subject. To tag all messages matching a pattern, 9139 use the <literal><tag-pattern></literal> function, which is bound 9140 to <quote>shift-T</quote> by default. Patterns are completable in the 9141 editor menu. Invoke the <literal><complete></literal> function 9142 (by default bound to <quote>Tab</quote>) after typing <quote>~</quote> 9143 to get a selectable list. Or you can select individual messages by hand 9144 using the <literal><tag-message></literal> function, which is 9145 bound to <quote>t</quote> by default. 9146 See <link linkend="patterns">patterns</link> for NeoMutt's pattern 9147 matching syntax. 9148 </para> 9149 <para> 9150 Once you have tagged the desired messages, you can use the 9151 <quote>tag-prefix</quote> operator, which is the <quote>;</quote> 9152 (semicolon) key by default. When the <quote>tag-prefix</quote> operator 9153 is used, the <emphasis>next</emphasis> operation will be applied to all 9154 tagged messages if that operation can be used in that manner. If the 9155 <link linkend="auto-tag">$auto_tag</link> variable is set, the next 9156 operation applies to the tagged messages automatically, without 9157 requiring the <quote>tag-prefix</quote>. 9158 </para> 9159 <para> 9160 In <link linkend="macro"><command>macro</command></link>s or 9161 <link linkend="push"><command>push</command></link> commands, you can 9162 use the <literal><tag-prefix-cond></literal> operator. If there 9163 are no tagged messages, NeoMutt will <quote>eat</quote> the rest of the 9164 macro to abort its execution. NeoMutt will stop <quote>eating</quote> 9165 the macro when it encounters the <literal><end-cond></literal> 9166 operator; after this operator the rest of the macro will be executed as 9167 normal. 9168 </para> 9169 </sect1> 9170 9171 <sect1 id="hooks"> 9172 <title>Using Hooks</title> 9173 <para> 9174 A <emphasis>hook</emphasis> is a concept found in many other programs 9175 which allows you to execute arbitrary commands before performing some 9176 operation. For example, you may wish to tailor your configuration based 9177 upon which mailbox you are reading, or to whom you are sending mail. In 9178 the NeoMutt world, a <emphasis>hook</emphasis> consists of a 9179 <link linkend="regex">regular expression</link> or 9180 <link linkend="patterns">pattern</link> along with a configuration 9181 option/command. See: 9182 </para> 9183 <itemizedlist> 9184 <listitem> 9185 <para> 9186 <link linkend="account-hook"><command>account-hook</command></link> 9187 </para> 9188 </listitem> 9189 <listitem> 9190 <para> 9191 <link linkend="charset-hook"><command>charset-hook</command></link> 9192 </para> 9193 <para> 9194 <link linkend="iconv-hook"><command>iconv-hook</command></link> 9195 </para> 9196 </listitem> 9197 <listitem> 9198 <para> 9199 <link linkend="index-format-hook"><command>index-format-hook</command></link> 9200 </para> 9201 </listitem> 9202 <listitem> 9203 <para> 9204 <link linkend="crypt-hook"><command>crypt-hook</command></link> 9205 </para> 9206 </listitem> 9207 <listitem> 9208 <para> 9209 <link linkend="fcc-save-hook"><command>fcc-save-hook</command></link> 9210 </para> 9211 <para> 9212 <link linkend="fcc-hook"><command>fcc-hook</command></link> 9213 </para> 9214 <para> 9215 <link linkend="save-hook"><command>save-hook</command></link> 9216 </para> 9217 </listitem> 9218 <listitem> 9219 <para> 9220 <link linkend="folder-hook"><command>folder-hook</command></link> 9221 </para> 9222 </listitem> 9223 <listitem> 9224 <para> 9225 <link linkend="mbox-hook"><command>mbox-hook</command></link> 9226 </para> 9227 </listitem> 9228 <listitem> 9229 <para> 9230 <link linkend="message-hook"><command>message-hook</command></link> 9231 </para> 9232 </listitem> 9233 <listitem> 9234 <para> 9235 <link linkend="open-hook"><command>open-hook</command></link> 9236 </para> 9237 <para> 9238 <link linkend="close-hook"><command>close-hook</command></link> 9239 </para> 9240 <para> 9241 <link linkend="append-hook"><command>append-hook</command></link> 9242 </para> 9243 </listitem> 9244 <listitem> 9245 <para> 9246 <link linkend="reply-hook"><command>reply-hook</command></link> 9247 </para> 9248 <para> 9249 <link linkend="send-hook"><command>send-hook</command></link> 9250 </para> 9251 <para> 9252 <link linkend="send2-hook"><command>send2-hook</command></link> 9253 </para> 9254 </listitem> 9255 <listitem> 9256 <para> 9257 <link linkend="global-hooks"><command>timeout-hook</command></link> 9258 </para> 9259 <para> 9260 <link linkend="global-hooks"><command>startup-hook</command></link> 9261 </para> 9262 <para> 9263 <link linkend="global-hooks"><command>shutdown-hook</command></link> 9264 </para> 9265 </listitem> 9266 <listitem> 9267 <para> 9268 <link linkend="unhook"><command>unhook</command></link> 9269 </para> 9270 </listitem> 9271 </itemizedlist> 9272 <para> 9273 for specific details on each type of <emphasis>hook</emphasis> 9274 available. Also see <link linkend="compose-flow">Message Composition 9275 Flow</link> for an overview of the composition process. 9276 </para> 9277 <note> 9278 <para> 9279 If a hook changes configuration settings, these changes remain 9280 effective until the end of the current NeoMutt session. As this is 9281 generally not desired, a <quote>default</quote> hook needs to be 9282 added before all other hooks of that type to restore configuration 9283 defaults. 9284 </para> 9285 </note> 9286 <example id="ex-default-hook"> 9287 <title>Specifying a <quote>default</quote> hook</title> 9288 9289<screen> 9290send-hook . 'unmy_hdr From:' 9291send-hook ~C'^b@b\.b$' my_hdr from: c@c.c 9292</screen> 9293 9294 </example> 9295 <para> 9296 In <xref linkend="ex-default-hook" />, by default the value of 9297 <link linkend="from">$from</link> and 9298 <link linkend="real-name">$real_name</link> is not overridden. When 9299 sending messages either To: or Cc: to <literal><b@b.b></literal>, 9300 the From: header is changed to <literal><c@c.c></literal>. 9301 </para> 9302 9303 <sect2 id="pattern-hook" xreflabel="Message Matching in Hooks"> 9304 <title>Message Matching in Hooks</title> 9305 <para> 9306 Hooks that act upon messages (<command>message-hook</command>, 9307 <command>reply-hook</command>, <command>send-hook</command>, 9308 <command>send2-hook</command>, <command>save-hook</command>, 9309 <command>fcc-hook</command>, <command>index-format-hook</command>) 9310 are evaluated in a slightly different 9311 manner. For the other types of hooks, a 9312 <link linkend="regex">regular expression</link> is sufficient. But in 9313 dealing with messages a finer grain of control is needed for matching 9314 since for different purposes you want to match different criteria. 9315 </para> 9316 <para> 9317 NeoMutt allows the use of the 9318 <link linkend="patterns">search pattern</link> language for matching 9319 messages in hook commands. This works in exactly the same way as it 9320 would when <emphasis>limiting</emphasis> or 9321 <emphasis>searching</emphasis> the mailbox, except that you are 9322 restricted to those operators which match information NeoMutt 9323 extracts from the header of the message (i.e., from, to, cc, date, 9324 subject, etc.). 9325 </para> 9326 <para> 9327 For example, if you wanted to set your return address based upon 9328 sending mail to a specific address, you could do something like: 9329 </para> 9330 9331<screen> 9332send-hook '~t ^user@work\.com$' 'my_hdr From: John Smith <user@host>' 9333</screen> 9334 9335 <para> 9336 which would execute the given command when sending mail to 9337 <emphasis>user@work.com</emphasis>. 9338 </para> 9339 <para> 9340 However, it is not required that you write the pattern to match using 9341 the full searching language. You can still specify a simple 9342 <emphasis>regular expression</emphasis> like the other hooks, in 9343 which case NeoMutt will translate your pattern into the full 9344 language, using the translation specified by the 9345 <link linkend="default-hook">$default_hook</link> variable. The 9346 pattern is translated at the time the hook is declared, so the value 9347 of <link linkend="default-hook">$default_hook</link> that is in 9348 effect at that time will be used. 9349 </para> 9350 </sect2> 9351 9352 <sect2 id="mailbox-hook" xreflabel="Mailbox Matching in Hooks"> 9353 <title>Mailbox Matching in Hooks</title> 9354 <para> 9355 Hooks that match against mailboxes (<command>folder-hook</command>, 9356 <command>mbox-hook</command>) apply both 9357 <link linkend="regex">regular expression</link> syntax as well as 9358 <link linkend="shortcuts">mailbox shortcut</link> expansion on the 9359 regex parameter. There is some overlap between these, so special 9360 attention should be paid to the first character of the regex. 9361 </para> 9362 9363<screen> 9364<emphasis role="comment"># Here, ^ will expand to "the current mailbox" not "beginning of string":</emphasis> 9365folder-hook ^/home/user/Mail/bar "set sort=threads" 9366<emphasis role="comment"># If you want ^ to be interpreted as "beginning of string", one workaround</emphasis> 9367<emphasis role="comment"># is to enclose the regex in parenthesis:</emphasis> 9368folder-hook (^/home/user/Mail/bar) "set sort=threads" 9369<emphasis role="comment"># This will expand to the default save folder for the alias "imap.example.com", which</emphasis> 9370<emphasis role="comment"># is probably not what you want:</emphasis> 9371folder-hook @imap.example.com "set sort=threads" 9372<emphasis role="comment"># A workaround is to use parenthesis or a backslash:</emphasis> 9373folder-hook (@imap.example.com) "set sort=threads" 9374folder-hook '\@imap.example.com' "set sort=threads" 9375</screen> 9376 9377 <para> 9378 Keep in mind that mailbox shortcut expansion on the regex parameter 9379 takes place when the hook is initially parsed, not when the hook is 9380 matching against a mailbox. When NeoMutt starts up and is reading the 9381 .neomuttrc, some mailbox shortcuts may not be usable. For example, 9382 the "current mailbox" shortcut, ^, will expand to an empty string 9383 because no mailbox has been opened yet. NeoMutt will issue an error 9384 for this case or if the mailbox shortcut results in an empty regex. 9385 </para> 9386 </sect2> 9387 </sect1> 9388 9389 <sect1 id="setenv"> 9390 <title>Managing the Environment</title> 9391 <para> 9392 You can alter the environment that NeoMutt passes on to its child 9393 processes using the <quote>setenv</quote> and <quote>unsetenv</quote> 9394 operators. (N.B. These follow NeoMutt-style syntax, not shell-style!) 9395 You can also query current environment values by prefixing 9396 a <quote>?</quote> character. 9397 </para> 9398 9399<screen> 9400setenv TERM vt100 9401setenv ORGANIZATION "The NeoMutt Development Team" 9402unsetenv DISPLAY 9403setenv ?LESS 9404</screen> 9405 9406 </sect1> 9407 9408 <sect1 id="query"> 9409 <title>External Address Queries</title> 9410 <para> 9411 NeoMutt supports connecting to external directory databases such as 9412 LDAP, ph/qi, bbdb, or NIS through a wrapper script which connects to 9413 NeoMutt using a simple interface. Using the 9414 <link linkend="query-command">$query_command</link> variable, you 9415 specify the wrapper command to use. For example: 9416 </para> 9417 <screen>set query_command = "mutt_ldap_query.pl %s"</screen> 9418 <para> 9419 The wrapper script should accept the query on the command-line. It 9420 should return a one line message, then each matching response on 9421 a single line, each line containing a tab separated address then name 9422 then some other optional information. On error, or if there are no 9423 matching addresses, return a non-zero exit code and a one line error 9424 message. 9425 </para> 9426 <para> 9427 An example multiple response output: 9428 </para> 9429 9430<screen> 9431Searching database ... 20 entries ... 3 matching: 9432me@cs.hmc.edu Michael Elkins mutt dude 9433blong@fiction.net Brandon Long mutt and more 9434roessler@does-not-exist.org Thomas Roessler mutt pgp 9435</screen> 9436 9437 <para> 9438 There are two mechanisms for accessing the query function of NeoMutt. 9439 One is to do a query from the index menu using the 9440 <literal><query></literal> function (default: Q). This will 9441 prompt for a query, then bring up the query menu which will list the 9442 matching responses. From the query menu, you can select addresses to 9443 create aliases, or to mail. You can tag multiple addresses to mail, 9444 start a new query, or have a new query appended to the current 9445 responses. 9446 </para> 9447 <para> 9448 The other mechanism for accessing the query function is for address 9449 completion, similar to the alias completion. In any prompt for address 9450 entry, you can use the <literal><complete-query></literal> 9451 function (default: ^T) to run a query based on the current address you 9452 have typed. Like aliases, NeoMutt will look for what you have typed 9453 back to the last space or comma. If there is a single response for that 9454 query, NeoMutt will expand the address in place. If there are multiple 9455 responses, NeoMutt will activate the query menu. At the query menu, you 9456 can select one or more addresses to be added to the prompt. 9457 </para> 9458 <note> 9459 <para> 9460 The query menu is affected by <link linkend="sort-alias">$sort_alias</link>, 9461 thus overruling the order of entries as generated by 9462 <link linkend="query-command">$query_command</link>. 9463 </para> 9464 </note> 9465 </sect1> 9466 9467 <sect1 id="mailbox-formats"> 9468 <title>Mailbox Formats</title> 9469 <para> 9470 NeoMutt supports reading and writing of four different local mailbox 9471 formats: mbox, MMDF, MH and Maildir. The mailbox type is auto detected, 9472 so there is no need to use a flag for different mailbox types. When 9473 creating new mailboxes, NeoMutt uses the default specified with the 9474 <link linkend="mbox-type">$mbox_type</link> variable. A short 9475 description of the formats follows. 9476 </para> 9477 <para> 9478 <emphasis>mbox</emphasis>. This is a widely used mailbox format for 9479 UNIX. All messages are stored in a single file. Each message has 9480 a line of the form: 9481 </para> 9482 <screen>From me@cs.hmc.edu Fri, 11 Apr 1997 11:44:56 PST</screen> 9483 <para> 9484 to denote the start of a new message (this is often referred to as the 9485 <quote>From_</quote> line). The mbox format requires mailbox locking, 9486 is prone to mailbox corruption with concurrently writing clients or 9487 misinterpreted From_ lines. Depending on the environment, new mail 9488 detection can be unreliable. Mbox folders are fast to open and easy to 9489 archive. 9490 </para> 9491 <para> 9492 <emphasis>MMDF</emphasis>. This is a variant of the 9493 <emphasis>mbox</emphasis> format. Each message is surrounded by lines 9494 containing <quote>^A^A^A^A</quote> (four times control-A's). The same 9495 problems as for mbox apply (also with finding the right message 9496 separator as four control-A's may appear in message bodies). 9497 </para> 9498 <para> 9499 <emphasis>MH</emphasis>. A radical departure from 9500 <emphasis>mbox</emphasis> and <emphasis>MMDF</emphasis>, a mailbox 9501 consists of a directory and each message is stored in a separate file. 9502 The filename indicates the message number (however, this is may not 9503 correspond to the message number NeoMutt displays). Deleted messages 9504 are renamed with a comma (<quote>,</quote>) prepended to the filename. 9505 NeoMutt detects this type of mailbox by looking for either 9506 <literal>.mh_sequences</literal> or <literal>.xmhcache</literal> files 9507 (needed to distinguish normal directories from MH mailboxes). MH is 9508 more robust with concurrent clients writing the mailbox, but still may 9509 suffer from lost flags; message corruption is less likely to occur than 9510 with mbox/mmdf. It's usually slower to open compared to mbox/mmdf since 9511 many small files have to be read (NeoMutt provides 9512 <xref linkend="header-caching" /> to greatly speed this process up). 9513 Depending on the environment, MH is not very disk-space efficient. 9514 </para> 9515 <para> 9516 <emphasis>Maildir</emphasis>. The newest of the mailbox formats, used 9517 by the Qmail MTA (a replacement for sendmail). Similar to 9518 <emphasis>MH</emphasis>, except that it adds three subdirectories of 9519 the mailbox: <emphasis>tmp</emphasis>, <emphasis>new</emphasis> and 9520 <emphasis>cur</emphasis>. Filenames for the messages are chosen in such 9521 a way they are unique, even when two programs are writing the mailbox 9522 over NFS, which means that no file locking is needed and corruption is 9523 very unlikely. Maildir maybe slower to open without caching in NeoMutt, 9524 it too is not very disk-space efficient depending on the environment. 9525 Since no additional files are used for metadata (which is embedded in 9526 the message filenames) and Maildir is locking-free, it's easy to sync 9527 across different machines using file-level synchronization tools. 9528 </para> 9529 </sect1> 9530 9531 <sect1 id="shortcuts"> 9532 <title>Mailbox Shortcuts</title> 9533 <para> 9534 There are a number of built in shortcuts which refer to specific 9535 mailboxes. These shortcuts can be used anywhere you are prompted for 9536 a file or mailbox path or in path-related configuration variables. Note 9537 that these only work at the beginning of a string. 9538 </para> 9539 9540 <table id="tab-mailbox-shortcuts"> 9541 <title>Mailbox shortcuts</title> 9542 <tgroup cols="2"> 9543 <thead> 9544 <row> 9545 <entry>Shortcut</entry> 9546 <entry>Refers to...</entry> 9547 </row> 9548 </thead> 9549 <tbody> 9550 <row> 9551 <entry><literal>!</literal></entry> 9552 <entry> 9553 your <link linkend="spool-file">$spool_file</link> (incoming) 9554 mailbox 9555 </entry> 9556 </row> 9557 <row> 9558 <entry><literal>></literal></entry> 9559 <entry> 9560 your <link linkend="mbox">$mbox</link> file 9561 </entry> 9562 </row> 9563 <row> 9564 <entry><literal><</literal></entry> 9565 <entry> 9566 your <link linkend="record">$record</link> file 9567 </entry> 9568 </row> 9569 <row> 9570 <entry><literal>^</literal></entry> 9571 <entry> 9572 the current mailbox 9573 </entry> 9574 </row> 9575 <row> 9576 <entry><literal>-</literal> or <literal>!!</literal></entry> 9577 <entry> 9578 the file you've last visited 9579 </entry> 9580 </row> 9581 <row> 9582 <entry><literal>~</literal></entry> 9583 <entry> 9584 your home directory 9585 </entry> 9586 </row> 9587 <row> 9588 <entry><literal>=</literal> or <literal>+</literal></entry> 9589 <entry> 9590 your <link linkend="folder">$folder</link> directory 9591 </entry> 9592 </row> 9593 <row> 9594 <entry><emphasis>@alias</emphasis></entry> 9595 <entry> 9596 to the 9597 <link linkend="default-save-mailbox">default save folder</link> 9598 as determined by the address of the alias 9599 </entry> 9600 </row> 9601 </tbody> 9602 </tgroup> 9603 </table> 9604 <para> 9605 For example, to store a copy of outgoing messages in the folder they 9606 were composed in, a 9607 <link linkend="folder-hook"><command>folder-hook</command></link> can 9608 be used to set <link linkend="record">$record</link>: 9609 </para> 9610 <screen>folder-hook . 'set record=^'</screen> 9611 <para> 9612 Note: the current mailbox shortcut, 9613 <quote><literal>^</literal></quote>, has no value in some cases. No 9614 mailbox is opened when NeoMutt is invoked to send an email from the 9615 command-line. In interactive mode, NeoMutt reads the muttrc before 9616 opening the mailbox, so immediate expansion won't work as expected 9617 either. This can be an issue when trying to directly assign to <link 9618 linkend="record">$record</link>, but also affects the <link 9619 linkend="fcc-hook">fcc-hook</link> mailbox, which is expanded 9620 immediately too. The folder-hook example above works because the 9621 command is executed later, when the folder-hook fires. 9622 </para> 9623 </sect1> 9624 9625 <sect1 id="using-lists"> 9626 <title>Handling Mailing Lists</title> 9627 <para> 9628 NeoMutt has a few configuration options that make dealing with large 9629 amounts of mail easier. The first thing you must do is to let NeoMutt 9630 know what addresses you consider to be mailing lists (technically this 9631 does not have to be a mailing list, but that is what it is most often 9632 used for), and what lists you are subscribed to. This is accomplished 9633 through the use of the 9634 <link linkend="lists"><command>lists</command></link> and 9635 <link linkend="lists"><command>subscribe</command></link> commands in 9636 your <literal>.neomuttrc</literal>. Alternatively or additionally, you 9637 can set <link linkend="auto-subscribe">$auto_subscribe</link> to 9638 automatically subscribe addresses found in a <literal>List-Post</literal> 9639 header. 9640 </para> 9641 <para> 9642 Now that NeoMutt knows what your mailing lists are, it can do several 9643 things, the first of which is the ability to show the name of a list 9644 through which you received a message (i.e., of a subscribed list) in 9645 the <emphasis>index</emphasis> menu display. This is useful to 9646 distinguish between personal and list mail in the same mailbox. In the 9647 <link linkend="index-format">$index_format</link> variable, the expando 9648 <quote>%L</quote> will print the string <quote>To <list></quote> 9649 when <quote>list</quote> appears in the <quote>To</quote> field, and 9650 <quote>Cc <list></quote> when it appears in the <quote>Cc</quote> 9651 field (otherwise it prints the name of the author). 9652 </para> 9653 <para> 9654 Often times the <quote>To</quote> and <quote>Cc</quote> fields in 9655 mailing list messages tend to get quite large. Most people do not 9656 bother to remove the author of the message they reply to from the list, 9657 resulting in two or more copies being sent to that person. The 9658 <literal><list-reply></literal> function, which by default is 9659 bound to <quote>L</quote> in the <emphasis>index</emphasis> menu and 9660 <emphasis>pager</emphasis>, helps reduce the clutter by only replying 9661 to the known mailing list addresses instead of all recipients (except 9662 as specified by <literal>Mail-Followup-To</literal>, see below). 9663 </para> 9664 <para> 9665 NeoMutt also supports the <literal>Mail-Followup-To</literal> header. 9666 When you send a message to a list of recipients which includes one or 9667 several known mailing lists, and if the 9668 <link linkend="followup-to">$followup_to</link> option is set, NeoMutt 9669 will generate a Mail-Followup-To header. If any of the recipients are 9670 subscribed mailing lists, this header will contain all the recipients 9671 to whom you send this message, but not your address. This indicates 9672 that group-replies or list-replies (also known as 9673 <quote>followups</quote>) to this message should only be sent to the 9674 original recipients of the message, and not separately to you - you'll 9675 receive your copy through one of the mailing lists you are subscribed 9676 to. If none of the recipients are subscribed mailing lists, the header 9677 will also contain your address, ensuring you receive a copy of replies. 9678 </para> 9679 <para> 9680 Conversely, when group-replying or list-replying to a message which has 9681 a <literal>Mail-Followup-To</literal> header, NeoMutt will respect this 9682 header if the 9683 <link linkend="honor-followup-to">$honor_followup_to</link> 9684 configuration variable is set. Using 9685 <link linkend="list-reply">list-reply</link> will in this case also 9686 make sure that the reply goes to the mailing list, even if it's not 9687 specified in the list of recipients in the 9688 <literal>Mail-Followup-To</literal>. 9689 </para> 9690 <note> 9691 <para> 9692 When header editing is enabled, you can create 9693 a <literal>Mail-Followup-To</literal> header manually. NeoMutt will 9694 only auto-generate this header if it doesn't exist when you send the 9695 message. 9696 </para> 9697 </note> 9698 <para> 9699 The other method some mailing list admins use is to generate 9700 a <quote>Reply-To</quote> field which points back to the mailing list 9701 address rather than the author of the message. This can create problems 9702 when trying to reply directly to the author in private, since most mail 9703 clients will automatically reply to the address given in the 9704 <quote>Reply-To</quote> field. NeoMutt uses the 9705 <link linkend="reply-to">$reply_to</link> variable to help decide which 9706 address to use. If set to <emphasis>ask-yes</emphasis> or 9707 <emphasis>ask-no</emphasis>, you will be prompted as to whether or not 9708 you would like to use the address given in the <quote>Reply-To</quote> 9709 field, or reply directly to the address given in the 9710 <quote>From</quote> field. When set to <emphasis>yes</emphasis>, the 9711 <quote>Reply-To</quote> field will be used when present. 9712 </para> 9713 <para> 9714 You can change or delete the <quote>X-Label:</quote> field within 9715 NeoMutt using the <quote>edit-label</quote> command, bound to the 9716 <quote>y</quote> key by default. This works for tagged messages, too. 9717 While in the edit-label function, pressing the <complete> binding 9718 (TAB, by default) will perform completion against all labels currently 9719 in use. 9720 </para> 9721 <para> 9722 Lastly, NeoMutt has the ability to <link linkend="sort">sort</link> the 9723 mailbox into <link linkend="threads">threads</link>. A thread is 9724 a group of messages which all relate to the same subject. This is 9725 usually organized into a tree-like structure where a message and all of 9726 its replies are represented graphically. If you've ever used a threaded 9727 news client, this is the same concept. It makes dealing with large 9728 volume mailing lists easier because you can easily delete uninteresting 9729 threads and quickly find topics of value. 9730 </para> 9731 </sect1> 9732 9733 <sect1 id="display-munging"> 9734 <title>Display Munging</title> 9735 <para> 9736 Working within the confines of a console or terminal window, it is 9737 often useful to be able to modify certain information elements in 9738 a non-destructive way – to change how they display, without changing 9739 the stored value of the information itself. This is especially so of 9740 message subjects, which may often be polluted with extraneous metadata 9741 that either is reproduced elsewhere, or is of secondary interest. 9742 </para> 9743 <cmdsynopsis> 9744 <command>subjectrx</command> 9745 <arg choice="plain"> 9746 <replaceable class="parameter">pattern</replaceable> 9747 </arg> 9748 <arg choice="plain"> 9749 <replaceable class="parameter">replacement</replaceable> 9750 </arg> 9751 <command>unsubjectrx</command> 9752 <group choice="req"> 9753 <arg choice="plain"> 9754 <replaceable class="parameter">*</replaceable> 9755 </arg> 9756 <arg choice="plain"> 9757 <replaceable class="parameter">pattern</replaceable> 9758 </arg> 9759 </group> 9760 </cmdsynopsis> 9761 <para> 9762 <literal>subjectrx</literal> specifies a regular expression 9763 <quote>pattern</quote> which, if detected in a message subject, causes 9764 the subject to be replaced with the <quote>replacement</quote> value. 9765 The replacement is subject to substitutions in the same way as for the 9766 <link linkend="spam">spam</link> command: <literal>%L</literal> for the 9767 text to the left of the match, <literal>%R</literal> for text to the 9768 right of the match, and <literal>%1</literal> for the first subgroup in 9769 the match (etc). If you simply want to erase the match, set it to 9770 <quote>%L%R</quote>. Any number of <literal>subjectrx</literal> 9771 commands may coexist. 9772 </para> 9773 <para> 9774 Note this well: the <quote>replacement</quote> value replaces the 9775 entire subject, not just the match! 9776 </para> 9777 <para> 9778 <literal>unsubjectrx</literal> removes a given subjectrx from the 9779 substitution list. If <literal>*</literal> is used as the pattern, all 9780 substitutions will be removed. 9781 </para> 9782 <example id="ex-subjectrx"> 9783 <title>Subject Munging</title> 9784 9785<screen> 9786<emphasis role="comment"># Erase [rt #12345] tags from Request Tracker (RT) e-mails</emphasis> 9787subjectrx '\[rt #[0-9]+\] *' '%L%R' 9788<emphasis role="comment"># Servicedesk is another RT that sends more complex subjects.</emphasis> 9789<emphasis role="comment"># Keep the ticket number.</emphasis> 9790subjectrx '\[servicedesk #([0-9]+)\] ([^.]+)\.([^.]+) - (new|open|pending|update) - ' '%L[#%1] %R' 9791<emphasis role="comment"># Strip out annoying [listname] prefixes in subjects</emphasis> 9792subjectrx '\[[^]]*\]:? *' '%L%R' 9793</screen> 9794 9795 </example> 9796 </sect1> 9797 9798 <sect1 id="new-mail"> 9799 <title>New Mail Detection</title> 9800 <para> 9801 NeoMutt supports setups with multiple folders, allowing all of them to 9802 be monitored for new mail (see <xref linkend="mailboxes" /> for 9803 details). 9804 </para> 9805 9806 <sect2 id="new-mail-formats"> 9807 <title>How New Mail Detection Works</title> 9808 <para> 9809 For Mbox and Mmdf folders, new mail is detected by comparing access 9810 and/or modification times of files: NeoMutt assumes a folder has new 9811 mail if it wasn't accessed after it was last modified. Utilities like 9812 <literal>biff</literal> or <literal>frm</literal> or any other 9813 program which accesses the mailbox might cause NeoMutt to never 9814 detect new mail for that mailbox if they do not properly reset the 9815 access time. Other possible causes of NeoMutt not detecting new mail 9816 in these folders are backup tools (updating access times) or 9817 filesystems mounted without access time update support (for Linux 9818 systems, see the <literal>relatime</literal> option). 9819 </para> 9820 <note> 9821 <para> 9822 Contrary to older NeoMutt releases, it now maintains the new mail 9823 status of a folder by properly resetting the access time if the 9824 folder contains at least one message which is neither read, nor 9825 deleted, nor marked as old. 9826 </para> 9827 </note> 9828 <para> 9829 In cases where new mail detection for Mbox or Mmdf folders appears to 9830 be unreliable, the 9831 <link linkend="check-mbox-size">$check_mbox_size</link> option can be 9832 used to make NeoMutt track and consult file sizes for new mail 9833 detection instead which won't work for size-neutral changes. 9834 </para> 9835 <para> 9836 New mail for Maildir is assumed if there is one message in the 9837 <literal>new/</literal> subdirectory which is not marked deleted (see 9838 <link linkend="maildir-trash">$maildir_trash</link>). For MH folders, 9839 a mailbox is considered having new mail if there's at least one 9840 message in the <quote>unseen</quote> sequence as specified by 9841 <link linkend="mh-seq-unseen">$mh_seq_unseen</link>. Optionally, 9842 <link linkend="new-mail-command">$new_mail_command</link> can be 9843 configured to execute an external program every time new mail is 9844 detected in the current inbox. 9845 </para> 9846 <para> 9847 NeoMutt does not poll POP3 folders for new mail, it only periodically 9848 checks the currently opened folder (if it's a POP3 folder). 9849 </para> 9850 <para> 9851 For IMAP, by default NeoMutt uses recent message counts provided by 9852 the server to detect new mail. If the 9853 <link linkend="imap-idle">$imap_idle</link> option is set, it'll use 9854 the IMAP IDLE extension if advertised by the server. 9855 </para> 9856 <para> 9857 The <link linkend="mail-check-recent">$mail_check_recent</link> 9858 option changes whether NeoMutt will notify you of new mail in an 9859 already visited mailbox. When set (the default) it will only notify 9860 you of new mail received since the last time you opened the mailbox. 9861 When unset, NeoMutt will notify you of any new mail in the mailbox. 9862 </para> 9863 </sect2> 9864 9865 <sect2 id="new-mail-polling"> 9866 <title>Polling For New Mail</title> 9867 <para> 9868 When in the index menu and being idle (also see 9869 <link linkend="timeout">$timeout</link>), NeoMutt periodically checks 9870 for new mail in all folders which have been configured via the 9871 <command>mailboxes</command> command. The interval depends on the 9872 folder type: for local/IMAP folders it consults 9873 <link linkend="mail-check">$mail_check</link> and 9874 <link linkend="pop-check-interval">$pop_check_interval</link> for POP 9875 folders. 9876 </para> 9877 <para> 9878 Outside the index menu the directory browser supports checking for 9879 new mail using the <literal><check-new></literal> function 9880 which is unbound by default. Pressing TAB will bring up a menu 9881 showing the files specified by the <command>mailboxes</command> 9882 command, and indicate which contain new messages. NeoMutt will 9883 automatically enter this mode when invoked from the command line with 9884 the <literal>-y</literal> option, or from the index/pager via the 9885 <literal><browse-mailboxes></literal> function. 9886 </para> 9887 <para> 9888 For the pager, index and directory browser menus, NeoMutt contains 9889 the <literal><mailbox-list></literal> function (bound to 9890 <quote>.</quote> by default) which will print a list of folders with 9891 new mail in the command line at the bottom of the screen. 9892 </para> 9893 <para> 9894 For the index, by default NeoMutt displays the number of mailboxes 9895 with new mail in the status bar, please refer to the 9896 <link linkend="status-format">$status_format</link> variable for 9897 details. 9898 </para> 9899 <para> 9900 When changing folders, NeoMutt fills the prompt with the first folder 9901 from the mailboxes list containing new mail (if any), pressing 9902 <literal><Space></literal> will cycle through folders with new 9903 mail. The (by default unbound) function 9904 <literal><next-unread-mailbox></literal> in the index can be 9905 used to immediately open the next folder with unread mail (if any). 9906 </para> 9907 </sect2> 9908 9909 <sect2 id="new-mail-monitoring"> 9910 <title>Monitoring New Mail</title> 9911 <para> 9912 When the <emphasis>Inotify</emphasis>mechanism for monitoring of 9913 files is supported (Linux only) and not disabled at compilation time, 9914 NeoMutt immediately notifies about new mail for all folders configured 9915 via the <link linkend="mailboxes"><command>mailboxes</command></link> 9916 command. Dependent on <link linkend="mailbox-formats">mailbox format</link> 9917 also added <emphasis>old</emphasis>mails are tracked (not for Maildir). 9918 </para> 9919 <para> 9920 No configuration variables are available. Trace output is given when 9921 debugging is enabled via <link linkend="tab-commandline-options">command line option</link> 9922 <literal>-d3</literal>. The lower level 2 only shows errors, the 9923 higher level 5 all including raw Inotify events. 9924 </para> 9925 <note> 9926 <para> 9927 Getting events about new mail is limited to the capabilities of the 9928 underlying mechanism. <emphasis>inotify</emphasis>only reports 9929 local changes, i. e. new mail notification works for mails 9930 delivered by an agent on the same machine as NeoMutt, but not when 9931 delivered remotely on a network file system as nfs. also the 9932 monitoring handles might fail in rare conditions, so you better 9933 don't completely rely on this feature. 9934 </para> 9935 </note> 9936 <note> 9937 <para> 9938 When using Maildir, you don't have to manually specify all your mailboxes. You can use this command instead: 9939 </para> 9940<screen> 9941mailboxes `find ~/.mail/ -type d -name cur | sed -e 's:/cur/*$::' -e 's/ /\\ /g' | sort | tr '\n' ' '` 9942</screen> 9943 </note> 9944 </sect2> 9945 9946 <sect2 id="calc-mailbox-counts"> 9947 <title>Calculating Mailbox Message Counts</title> 9948 <para> 9949 If <link linkend="mail-check-stats">$mail_check_stats</link> is set, 9950 NeoMutt will periodically calculate the unread, flagged, and total 9951 message counts for each mailbox watched by the 9952 <command>mailboxes</command> command. This calculation takes place at 9953 the same time as new mail polling, but is controlled by a separate 9954 timer: 9955 <link linkend="mail-check-stats-interval">$mail_check_stats_interval</link>. 9956 </para> 9957 <para> 9958 The sidebar can display these message counts. See 9959 <link linkend="sidebar-format">$sidebar_format</link>. 9960 </para> 9961 </sect2> 9962 </sect1> 9963 9964 <sect1 id="editing-threads"> 9965 <title>Editing Threads</title> 9966 <para> 9967 NeoMutt has the ability to dynamically restructure threads that are 9968 broken either by misconfigured software or bad behavior from some 9969 correspondents. This allows to clean your mailboxes from these 9970 annoyances which make it hard to follow a discussion. 9971 </para> 9972 9973 <sect2 id="link-threads"> 9974 <title>Linking Threads</title> 9975 <para> 9976 Some mailers tend to <quote>forget</quote> to correctly set the 9977 <quote>In-Reply-To:</quote> and <quote>References:</quote> headers 9978 when replying to a message. This results in broken discussions 9979 because NeoMutt has not enough information to guess the correct 9980 threading. You can fix this by tagging a number of replies, then 9981 moving to the parent message and using the <literal> 9982 <link-threads> </literal> function (bound to & by default). 9983 The replies will then be connected to this parent message. 9984 </para> 9985 </sect2> 9986 9987 <sect2 id="break-threads"> 9988 <title>Breaking Threads</title> 9989 <para> 9990 On mailing lists, some people are in the bad habit of starting a new 9991 discussion by hitting <quote>reply</quote> to any message from the 9992 list and changing the subject to a totally unrelated one. You can fix 9993 such threads by using the <literal><break-thread></literal> 9994 function (bound by default to #), which will turn the subthread 9995 starting from the current message into a whole different thread. 9996 </para> 9997 </sect2> 9998 </sect1> 9999 10000 <sect1 id="dsn"> 10001 <title>Delivery Status Notification (DSN) Support</title> 10002 <para> 10003 RFC1894 defines a set of MIME content types for relaying information 10004 about the status of electronic mail messages. These can be thought of 10005 as <quote>return receipts.</quote> 10006 </para> 10007 <para> 10008 To support DSN, there are two variables. 10009 <link linkend="dsn-notify">$dsn_notify</link> is used to request 10010 receipts for different results (such as failed message, message 10011 delivered, etc.). <link linkend="dsn-return">$dsn_return</link> 10012 requests how much of your message should be returned with the receipt 10013 (headers or full message). 10014 </para> 10015 <para> 10016 When using <link linkend="sendmail">$sendmail</link> for mail delivery, 10017 you need to use either Berkeley sendmail 8.8.x (or greater) a MTA 10018 supporting DSN command line options compatible to Sendmail: The -N and 10019 -R options can be used by the mail client to make requests as to what 10020 type of status messages should be returned. Please consider your MTA 10021 documentation whether DSN is supported. 10022 </para> 10023 <para> 10024 For SMTP delivery using <link linkend="smtp-url">$smtp_url</link>, it 10025 depends on the capabilities announced by the server whether NeoMutt 10026 will attempt to request DSN or not. 10027 </para> 10028 </sect1> 10029 10030 <sect1 id="urlview"> 10031 <title>Start a WWW Browser on URLs</title> 10032 <para> 10033 If a message contains URLs, it is efficient to get a menu with all the 10034 URLs and start a WWW browser on one of them. This functionality is 10035 provided by the external urlview program which can be retrieved at 10036 <ulink url="ftp://ftp.mutt.org/mutt/contrib/">ftp://ftp.mutt.org/mutt/contrib/</ulink> 10037 and the configuration commands: 10038 </para> 10039 10040<screen> 10041macro index \cb |urlview\n 10042macro pager \cb |urlview\n 10043</screen> 10044 10045 </sect1> 10046 10047 <sect1 id="echo"> 10048 <title>Echoing Text</title> 10049 <para>Usage:</para> 10050 <cmdsynopsis> 10051 <command>echo</command> 10052 <arg choice="plain"> 10053 <replaceable class="parameter">message</replaceable> 10054 </arg> 10055 </cmdsynopsis> 10056 <para> 10057 You can print messages to the message window using the "echo" command. 10058 This might be useful after a macro finishes executing. After printing 10059 the message, echo will pause for the number of seconds specified by 10060 <link linkend="sleep-time">$sleep_time</link>. 10061 </para> 10062 10063<screen> 10064echo "Sourcing muttrc file" 10065unset confirm_append 10066macro index ,a "<save-message>=archive<enter><enter-command>echo 'Saved to archive'<enter>" 10067</screen> 10068 10069 </sect1> 10070 10071 <sect1 id="compose-flow"> 10072 <title>Message Composition Flow</title> 10073 <para> 10074 This is a brief overview of the steps NeoMutt takes during message 10075 composition. It also shows the order and timing of hook execution. 10076 </para> 10077 <itemizedlist> 10078 <listitem> 10079 <para>Reply envelope settings. 10080 <link linkend="reverse-name">$reverse_name</link>processing. To, Cc, 10081 Subject, References header defaults. 10082 </para> 10083 </listitem> 10084 <listitem> 10085 <para> 10086 <link linkend="my-hdr">my_hdr</link>processing for To, Cc, Bcc, 10087 Subject headers. 10088 </para> 10089 </listitem> 10090 <listitem> 10091 <para>Prompts for To, Cc, Bcc, Subject headers. See 10092 <link linkend="ask-cc">$ask_cc</link>, 10093 <link linkend="ask-bcc">$ask_bcc</link>, 10094 <link linkend="fast-reply">$fast_reply</link>.</para> 10095 </listitem> 10096 <listitem> 10097 <para> 10098 From header setting. Note: this is so 10099 <link linkend="send-hook">send-hook</link>s below can match ~P, but 10100 From is re-set further below in case a send-hook changes the value. 10101 </para> 10102 </listitem> 10103 <listitem> 10104 <para> 10105 <link linkend="reply-hook">reply-hook</link> 10106 </para> 10107 </listitem> 10108 <listitem> 10109 <para> 10110 <link linkend="send-hook">send-hook</link> 10111 </para> 10112 </listitem> 10113 <listitem> 10114 <para>From header setting.</para> 10115 </listitem> 10116 <listitem> 10117 <para> 10118 <link linkend="my-hdr">my_hdr</link> processing for From, Reply-To, 10119 Message-ID and user-defined headers. The To, Cc, Bcc, Subject, and 10120 Return-Path headers are ignored at this stage. 10121 </para> 10122 </listitem> 10123 <listitem> 10124 <para>Message body and signature generation.</para> 10125 </listitem> 10126 <listitem> 10127 <para> 10128 <link linkend="send2-hook">send2-hook</link> 10129 </para> 10130 </listitem> 10131 <listitem> 10132 <para> 10133 <link linkend="real-name">$real_name</link>part of From header setting. 10134 </para> 10135 </listitem> 10136 <listitem> 10137 <para> 10138 <link linkend="editor">$editor</link>invocation for the message. 10139 </para> 10140 </listitem> 10141 <listitem> 10142 <para> 10143 <link linkend="send2-hook">send2-hook</link> 10144 </para> 10145 </listitem> 10146 <listitem> 10147 <para>Cryptographic settings.</para> 10148 </listitem> 10149 <listitem> 10150 <para> 10151 <link linkend="fcc-hook">fcc-hook</link>. Fcc setting.</para> 10152 </listitem> 10153 <listitem> 10154 <para> 10155 <link linkend="compose-menu">Compose menu</link>. Note: 10156 <link linkend="send2-hook">send2-hook</link> 10157 is evaluated each time the headers are changed. 10158 </para> 10159 </listitem> 10160 <listitem> 10161 <para>Message encryption and signing. Key selection.</para> 10162 </listitem> 10163 <listitem> 10164 <para> 10165 Fcc saving if <link 10166 linkend="fcc-before-send">$fcc_before_send</link> is set. (Note the 10167 variable documentation for caveats of Fcc'ing before sending.) 10168 </para> 10169 </listitem> 10170 <listitem> 10171 <para>Message sending.</para> 10172 </listitem> 10173 <listitem> 10174 <para> 10175 Fcc saving if <link linkend="fcc-before-send">$fcc_before_send</link> 10176 is unset (the default). The Fcc used to be saved before sending the 10177 message. It is now by default saved afterwards, but if the saving 10178 fails, the user is prompted. 10179 </para> 10180 </listitem> 10181 </itemizedlist> 10182 </sect1> 10183 10184 <sect1 id="misc-topics"> 10185 <title>Miscellany</title> 10186 <para> 10187 This section documents various features that fit nowhere else. 10188 </para> 10189 <variablelist> 10190 <varlistentry> 10191 <term>Address normalization</term> 10192 <listitem> 10193 <para> 10194 NeoMutt normalizes all e-mail addresses to the simplest form 10195 possible. If an address contains a real_name, the form 10196 <emphasis>Joe User <joe@example.com></emphasis> is used and 10197 the pure e-mail address without angle brackets otherwise, i.e. 10198 just <emphasis>joe@example.com</emphasis>. 10199 </para> 10200 <para> 10201 This normalization affects all headers NeoMutt generates 10202 including aliases. 10203 </para> 10204 </listitem> 10205 </varlistentry> 10206 <varlistentry> 10207 <term>Initial folder selection</term> 10208 <listitem> 10209 <para> 10210 The folder NeoMutt opens at startup is determined as follows: the 10211 folder specified in the <literal>$MAIL</literal> environment 10212 variable if present. Otherwise, the value of 10213 <literal>$MAILDIR</literal> is taken into account. If that isn't 10214 present either, NeoMutt takes the user's mailbox in the mailspool 10215 as determined at compile-time (which may also reside in the home 10216 directory). The <link linkend="spool-file">$spool_file</link> 10217 setting overrides this selection. Highest priority has the 10218 mailbox given with the <literal>-f</literal> command line option. 10219 </para> 10220 </listitem> 10221 </varlistentry> 10222 </variablelist> 10223 </sect1> 10224 </chapter> 10225 10226 <chapter id="mimesupport"> 10227 <title>NeoMutt's MIME Support</title> 10228 <para> 10229 Quite a bit of effort has been made to make NeoMutt the premier text-mode 10230 MIME MUA. Every effort has been made to provide the functionality that 10231 the discerning MIME user requires, and the conformance to the standards 10232 wherever possible. When configuring NeoMutt for MIME, there are two extra 10233 types of configuration files which NeoMutt uses. One is the 10234 <literal>mime.types</literal> file, which contains the mapping of file 10235 extensions to IANA MIME types. The other is the 10236 <literal>mailcap</literal> file, which specifies the external commands to 10237 use for handling specific MIME types. 10238 </para> 10239 10240 <sect1 id="using-mime"> 10241 <title>Using MIME in NeoMutt</title> 10242 10243 <sect2 id="mime-overview"> 10244 <title>MIME Overview</title> 10245 <para> 10246 MIME is short for <quote>Multipurpose Internet Mail Extension</quote> 10247 and describes mechanisms to internationalize and structure mail 10248 messages. Before the introduction of MIME, messages had a single text 10249 part and were limited to us-ascii header and content. With MIME, 10250 messages can have attachments (and even attachments which itself have 10251 attachments and thus form a tree structure), nearly arbitrary 10252 characters can be used for sender names, recipients and subjects. 10253 </para> 10254 <para> 10255 Besides the handling of non-ascii characters in message headers, to 10256 NeoMutt the most important aspect of MIME are so-called MIME types. 10257 These are constructed using a <emphasis>major</emphasis> and 10258 <emphasis>minor</emphasis> type separated by a forward slash. These 10259 specify details about the content that follows. Based upon these, 10260 NeoMutt decides how to handle this part. The most popular major type 10261 is <quote><literal>text</literal></quote> with minor types for 10262 plain text, HTML and various other formats. Major types also exist 10263 for images, audio, video and of course general application data (e.g. 10264 to separate cryptographically signed data with a signature, send 10265 office documents, and in general arbitrary binary data). There's also 10266 the <literal>multipart</literal> major type which represents the root 10267 of a subtree of MIME parts. A list of supported MIME types can be 10268 found in <xref linkend="supported-mime-types" />. 10269 </para> 10270 <para> 10271 MIME also defines a set of encoding schemes for transporting MIME 10272 content over the network: <literal>7bit</literal>, 10273 <literal>8bit</literal>, <literal>quoted-printable</literal>, 10274 <literal>base64</literal> and <literal>binary</literal>. There're 10275 some rules when to choose what for encoding headers and/or body (if 10276 needed), and NeoMutt will in general make a good choice. 10277 </para> 10278 <para> 10279 NeoMutt does most of MIME encoding/decoding behind the scenes to form 10280 messages conforming to MIME on the sending side. On reception, it can 10281 be flexibly configured as to how what MIME structure is displayed 10282 (and if it's displayed): these decisions are based on the content's 10283 MIME type. There are three areas/menus in dealing with MIME: the 10284 pager (while viewing a message), the attachment menu and the compose 10285 menu. 10286 </para> 10287 </sect2> 10288 10289 <sect2 id="mime-pager"> 10290 <title>Viewing MIME Messages in the Pager</title> 10291 <para> 10292 When you select a message from the index and view it in the pager, 10293 NeoMutt decodes as much of a message as possible to a text 10294 representation. NeoMutt internally supports a number of MIME types, 10295 including the <literal>text</literal> major type (with all minor 10296 types), the <literal>message/rfc822</literal> (mail messages) type 10297 and some <literal>multipart</literal> types. In addition, it 10298 recognizes a variety of PGP MIME types, including PGP/MIME and 10299 <literal>application/pgp</literal>. 10300 </para> 10301 <para> 10302 NeoMutt will denote attachments with a couple lines describing them. 10303 These lines are of the form: 10304 </para> 10305 10306<screen> 10307[-- Attachment #1: Description --] 10308[-- Type: text/plain, Encoding: 7bit, Size: 10000 --] 10309</screen> 10310 10311 <para> 10312 Where the <emphasis>Description</emphasis> is the description or 10313 filename given for the attachment, and the 10314 <emphasis>Encoding</emphasis> is one of the already mentioned content 10315 encodings. 10316 </para> 10317 <para> 10318 If NeoMutt cannot deal with a MIME type, it will display a message 10319 like: 10320 </para> 10321 10322<screen> 10323[-- image/gif is unsupported (use 'v' to view this part) --] 10324</screen> 10325 10326 </sect2> 10327 10328 <sect2 id="attach-menu"> 10329 <title>The Attachment Menu</title> 10330 <para> 10331 The default binding for <literal><view-attachments></literal> 10332 is <quote>v</quote>, which displays the attachment menu for 10333 a message. The attachment menu displays a list of the attachments in 10334 a message. From the attachment menu, you can save, print, pipe, 10335 delete, and view attachments. You can apply these operations to 10336 a group of attachments at once, by tagging the attachments and by 10337 using the <literal><tag-prefix></literal> operator. You can 10338 also reply to the current message from this menu, and only the 10339 current attachment (or the attachments tagged) will be quoted in your 10340 reply. You can view attachments as text, or view them using the 10341 mailcap viewer definition (the mailcap mechanism is explained later 10342 in detail). 10343 </para> 10344 <para> 10345 Finally, you can apply the usual message-related functions (like 10346 <link linkend="resend-message"><literal><resend-message></literal></link>, 10347 and the 10348 <literal><reply></literal> and 10349 <literal><forward></literal> functions) to attachments of type 10350 <literal>message/rfc822</literal>. 10351 </para> 10352 <para> 10353 See table <xref linkend="tab-attachment-bindings" /> for all 10354 available functions. 10355 </para> 10356 10357 <sect3 id="attach-viewers"> 10358 <title>Viewing Attachments</title> 10359 10360 <para> 10361 There are four(!) ways of viewing attachments, so the functions 10362 deserve some extra explanation. 10363 </para> 10364 10365 <variablelist> 10366 <varlistentry> 10367 <term> 10368 <literal><view-mailcap></literal> 10369 (default keybinding: m) 10370 </term> 10371 <listitem> 10372 <para> 10373 This will use the first matching mailcap entry. 10374 </para> 10375 <para> 10376 If no matching mailcap entries are found, it will abort with an 10377 error message. 10378 </para> 10379 </listitem> 10380 </varlistentry> 10381 10382 <varlistentry> 10383 <term> 10384 <literal><view-attach></literal> 10385 (default keybinding: <Enter>) 10386 </term> 10387 <listitem> 10388 <para> 10389 Mutt will display internally supported MIME types (see <xref 10390 linkend="mime-pager"/>) in the pager. This will respect 10391 <link linkend="auto-view">auto_view</link> settings, to determine 10392 whether to use a <literal>copiousoutput</literal> mailcap entry or 10393 just directly display the attachment. 10394 </para> 10395 <para> 10396 Other MIME types will use the first matching mailcap entry. 10397 </para> 10398 <para> 10399 If no matching mailcap entries are found, the attachment will 10400 be displayed in the pager as raw text. 10401 </para> 10402 </listitem> 10403 </varlistentry> 10404 10405 <varlistentry> 10406 <term> 10407 <literal><view-pager></literal> 10408 </term> 10409 <listitem> 10410 <para> 10411 Mutt will use the first matching 10412 <literal>copiousoutput</literal> mailcap entry to display the 10413 attachment in the pager (regardless of <link 10414 linkend="auto-view">auto_view</link> settings). 10415 </para> 10416 <para> 10417 If no matching mailcap entries are found, the attachment will 10418 be displayed in the pager as raw text. 10419 </para> 10420 </listitem> 10421 </varlistentry> 10422 10423 <varlistentry> 10424 <term> 10425 <literal><view-text></literal> 10426 (default keybinding: T) 10427 </term> 10428 <listitem> 10429 <para> 10430 The attachment will always be displayed in the pager as raw 10431 text. 10432 </para> 10433 </listitem> 10434 </varlistentry> 10435 </variablelist> 10436 </sect3> 10437 </sect2> 10438 10439 <sect2 id="compose-menu"> 10440 <title>The Compose Menu</title> 10441 <para> 10442 The compose menu is the menu you see before you send a message. It 10443 allows you to edit the recipient list, the subject, and other aspects 10444 of your message. It also contains a list of the attachments of your 10445 message, including the main body. From this menu, you can print, 10446 copy, filter, pipe, edit, compose, review, and rename an attachment 10447 or a list of tagged attachments. You can also modifying the 10448 attachment information, notably the type, encoding and description. 10449 </para> 10450 <para> 10451 Attachments appear as follows by default: 10452 </para> 10453 10454<screen> 10455- 1 [text/plain, 7bit, 1K] /tmp/neomutt-euler-8082-0 <no description> 10456 2 [applica/x-gunzip, base64, 422K] ~/src/neomutt-0.85.tar.gz <no description> 10457</screen> 10458 10459 <para> 10460 The <quote>-</quote> denotes that NeoMutt will delete the file after 10461 sending (or postponing, or canceling) the message. It can be toggled 10462 with the <literal><toggle-unlink></literal> command (default: 10463 u). The next field is the MIME content-type, and can be changed with 10464 the <literal><edit-type></literal> command (default: ^T). The 10465 next field is the encoding for the attachment, which allows a binary 10466 message to be encoded for transmission on 7bit links. It can be 10467 changed with the <literal><edit-encoding></literal> command 10468 (default: ^E). The next field is the size of the attachment, rounded 10469 to kilobytes or megabytes. The next field is the filename, which can 10470 be changed with the <literal><rename-file></literal> command 10471 (default: R). The final field is the description of the attachment, 10472 and can be changed with the 10473 <literal><edit-description></literal> command (default: d). See 10474 <link linkend="attach-format">$attach_format</link> for a full list 10475 of available expandos to format this display to your needs. 10476 </para> 10477 </sect2> 10478 </sect1> 10479 10480 <sect1 id="mime-types"> 10481 <title>MIME Type Configuration with <literal>mime.types</literal></title> 10482 <para> 10483 To get most out of MIME, it's important that a MIME part's content type 10484 matches the content as closely as possible so that the recipient's 10485 client can automatically select the right viewer for the content. 10486 However, there's no reliable way for NeoMutt to know how to detect every 10487 possible file type. Instead, it uses a simple plain text mapping file 10488 that specifies what file extension corresponds to what MIME type. This 10489 file is called <literal>mime.types</literal>. 10490 </para> 10491 <para> 10492 When you add an attachment to your mail message, NeoMutt searches the 10493 system <literal>mime.types</literal> file at 10494 <literal>/etc/mime.types</literal>, 10495 <literal>$SYSCONFDIR/mime.types</literal> or 10496 <literal>$PKGDATADIR/mime.types</literal> and then your personal 10497 <literal>mime.types</literal> file at 10498 <literal>$HOME/.mime.types</literal>. 10499 </para> 10500 <para> 10501 Where <literal>$HOME</literal> is your home directory. The 10502 <literal>$PKGDATADIR</literal> and the <literal>$SYSCONFDIR</literal> 10503 directories depend on where NeoMutt is installed: the former is the 10504 default for shared data, the latter for system configuration files. 10505 </para> 10506 <para> 10507 Each line starts with the full MIME type, followed by a space and 10508 space-separated list of file extensions. For example you could use: 10509 </para> 10510 <example id="ex-mime-types"> 10511 <title><literal>mime.types</literal></title> 10512 10513<screen> 10514application/postscript ps eps 10515application/pgp pgp 10516audio/x-aiff aif aifc aiff 10517</screen> 10518 10519 </example> 10520 <para> 10521 A sample <literal>mime.types</literal> file comes with the NeoMutt 10522 distribution, and should contain most of the MIME types you are likely 10523 to use. 10524 </para> 10525 <para> 10526 If NeoMutt can not determine the MIME type by the extension of the file 10527 you attach, it will run the command specified in 10528 <link linkend="mime-type-query-command">$mime_type_query_command</link>. 10529 If that command is not specified, NeoMutt will look at the file. If the 10530 file is free of binary information, NeoMutt will assume that the file 10531 is plain text, and mark it as <literal>text/plain</literal>. If the 10532 file contains binary information, then NeoMutt will mark it as 10533 <literal>application/octet-stream</literal>. You can change the MIME 10534 type that NeoMutt assigns to an attachment by using the 10535 <literal><edit-type></literal> command from the compose menu 10536 (default: ^T), see <xref linkend="supported-mime-types" /> for 10537 supported major types. NeoMutt recognizes all of these if the 10538 appropriate entry is found in the <literal>mime.types</literal> file. 10539 Non-recognized mime types should only be used if the recipient of the 10540 message is likely to be expecting such attachments. 10541 </para> 10542 10543 <table id="supported-mime-types"> 10544 <title>Supported MIME types</title> 10545 <tgroup cols="3"> 10546 <thead> 10547 <row> 10548 <entry>MIME major type</entry> 10549 <entry>Standard</entry> 10550 <entry>Description</entry> 10551 </row> 10552 </thead> 10553 <tbody> 10554 <row> 10555 <entry><literal>application</literal></entry> 10556 <entry>yes</entry> 10557 <entry>General application data</entry> 10558 </row> 10559 <row> 10560 <entry><literal>audio</literal></entry> 10561 <entry>yes</entry> 10562 <entry>Audio data</entry> 10563 </row> 10564 <row> 10565 <entry><literal>image</literal></entry> 10566 <entry>yes</entry> 10567 <entry>Image data</entry> 10568 </row> 10569 <row> 10570 <entry><literal>message</literal></entry> 10571 <entry>yes</entry> 10572 <entry>Mail messages, message status information</entry> 10573 </row> 10574 <row> 10575 <entry><literal>model</literal></entry> 10576 <entry>yes</entry> 10577 <entry>VRML and other modeling data</entry> 10578 </row> 10579 <row> 10580 <entry><literal>multipart</literal></entry> 10581 <entry>yes</entry> 10582 <entry>Container for other MIME parts</entry> 10583 </row> 10584 <row> 10585 <entry><literal>text</literal></entry> 10586 <entry>yes</entry> 10587 <entry>Text data</entry> 10588 </row> 10589 <row> 10590 <entry><literal>video</literal></entry> 10591 <entry>yes</entry> 10592 <entry>Video data</entry> 10593 </row> 10594 <row> 10595 <entry><literal>chemical</literal></entry> 10596 <entry>no</entry> 10597 <entry>Mostly molecular data</entry> 10598 </row> 10599 </tbody> 10600 </tgroup> 10601 </table> 10602 <para> 10603 MIME types are not arbitrary, they need to be assigned by 10604 <ulink url="http://www.iana.org/assignments/media-types/">IANA</ulink>. 10605 </para> 10606 </sect1> 10607 10608 <sect1 id="mailcap"> 10609 <title>MIME Viewer Configuration with Mailcap</title> 10610 <para> 10611 NeoMutt supports RFC1524 MIME Configuration, in particular the Unix 10612 specific format specified in Appendix A of RFC1524. This file format 10613 is commonly referred to as the <quote>mailcap</quote> format. Many MIME 10614 compliant programs utilize the mailcap format, allowing you to specify 10615 handling for all MIME types in one place for all programs. Programs 10616 known to use this format include Firefox, lynx and metamail. 10617 </para> 10618 <para> 10619 In order to handle various MIME types that NeoMutt doesn't have 10620 built-in support for, it parses a series of external configuration 10621 files to find an external handler. The default search string for these 10622 files is a colon delimited list containing the following files: 10623 </para> 10624 <orderedlist> 10625 <listitem> 10626 <para> 10627 <literal>$HOME/.mailcap</literal> 10628 </para> 10629 </listitem> 10630 <listitem> 10631 <para> 10632 <literal>$PKGDATADIR/mailcap</literal> 10633 </para> 10634 </listitem> 10635 <listitem> 10636 <para> 10637 <literal>$SYSCONFDIR/mailcap</literal> 10638 </para> 10639 </listitem> 10640 <listitem> 10641 <para> 10642 <literal>/etc/mailcap</literal> 10643 </para> 10644 </listitem> 10645 <listitem> 10646 <para> 10647 <literal>/usr/etc/mailcap</literal> 10648 </para> 10649 </listitem> 10650 <listitem> 10651 <para> 10652 <literal>/usr/local/etc/mailcap</literal> 10653 </para> 10654 </listitem> 10655 </orderedlist> 10656 <para> 10657 where <literal>$HOME</literal> is your home directory. The 10658 <literal>$PKGDATADIR</literal> and the <literal>$SYSCONFDIR</literal> 10659 directories depend on where NeoMutt is installed: the former is the 10660 default for shared data, the latter for system configuration files. 10661 </para> 10662 <para> 10663 The default search path can be obtained by running the following 10664 command: 10665 </para> 10666 <screen>neomutt -nF /dev/null -Q mailcap_path</screen> 10667 <para> 10668 In particular, the metamail distribution will install a mailcap file, 10669 usually as <literal>/usr/local/etc/mailcap</literal>, which contains 10670 some baseline entries. 10671 </para> 10672 10673 <sect2 id="mailcap-basics"> 10674 <title>The Basics of the Mailcap File</title> 10675 <para> 10676 A mailcap file consists of a series of lines which are comments, 10677 blank, or definitions. 10678 </para> 10679 <para> 10680 A comment line consists of a # character followed by anything you 10681 want. 10682 </para> 10683 <para> 10684 A blank line is blank. 10685 </para> 10686 <para> 10687 A definition line consists of a content type, a view command, and any 10688 number of optional fields. Each field of a definition line is divided 10689 by a semicolon <quote>;</quote> character. 10690 </para> 10691 <para> 10692 The content type is specified in the MIME standard 10693 <quote>type/subtype</quote> notation. For example, 10694 <literal>text/plain</literal>, <literal>text/html</literal>, 10695 <literal>image/gif</literal>, etc. In addition, the mailcap format 10696 includes two formats for wildcards, one using the special 10697 <quote>*</quote> subtype, the other is the implicit wild, where you 10698 only include the major type. For example, <literal>image/*</literal>, 10699 or <literal>video</literal> will match all image types and video 10700 types, respectively. 10701 </para> 10702 <para> 10703 The view command is a Unix command for viewing the type specified. 10704 There are two different types of commands supported. The default is 10705 to send the body of the MIME message to the command on stdin. You can 10706 change this behavior by using <literal>%s</literal> as a parameter to 10707 your view command. This will cause NeoMutt to save the body of the 10708 MIME message to a temporary file, and then call the view command with 10709 the <literal>%s</literal> replaced by the name of the temporary file. 10710 In both cases, NeoMutt will turn over the terminal to the view 10711 program until the program quits, at which time NeoMutt will remove 10712 the temporary file if it exists. This means that mailcap does 10713 <emphasis>not</emphasis> work out of the box with programs which 10714 detach themselves from the terminal right after starting, like 10715 <literal>open</literal> on Mac OS X. In order to nevertheless use 10716 these programs with mailcap, you probably need custom shell scripts. 10717 </para> 10718 <para> 10719 So, in the simplest form, you can send 10720 a <literal>text/plain</literal> message to the external pager more on 10721 standard input: 10722 </para> 10723 <screen>text/plain; more</screen> 10724 <para> 10725 Or, you could send the message as a file: 10726 </para> 10727 <screen>text/plain; more %s</screen> 10728 <para> 10729 Perhaps you would like to use lynx to interactively view 10730 a <literal>text/html</literal> message: 10731 </para> 10732 <screen>text/html; lynx %s</screen> 10733 <para> 10734 In this case, lynx does not support viewing a file from standard 10735 input, so you must use the <literal>%s</literal> syntax. 10736 </para> 10737 <note> 10738 <para> 10739 <emphasis>Some older versions of lynx contain a bug where they will 10740 check the mailcap file for a viewer for 10741 <literal>text/html</literal>. They will find the line which calls 10742 lynx, and run it. This causes lynx to continuously spawn itself 10743 to view the object.</emphasis> 10744 </para> 10745 </note> 10746 <para> 10747 On the other hand, maybe you don't want to use lynx interactively, 10748 you just want to have it convert the <literal>text/html</literal> to 10749 <literal>text/plain</literal>, then you can use: 10750 </para> 10751 <screen>text/html; lynx -dump %s | more</screen> 10752 <para> 10753 Perhaps you wish to use lynx to view <literal>text/html</literal> 10754 files, and a pager on all other text formats, then you would use the 10755 following: 10756 </para> 10757 10758<screen> 10759text/html; lynx %s 10760text/*; more 10761</screen> 10762 10763 </sect2> 10764 10765 <sect2 id="secure-mailcap"> 10766 <title>Secure Use of Mailcap</title> 10767 <para> 10768 The interpretation of shell meta-characters embedded in MIME 10769 parameters can lead to security problems in general. NeoMutt tries to 10770 quote parameters in expansion of <literal>%s</literal> syntaxes 10771 properly, and avoids risky characters by substituting them, see the 10772 <link linkend="mailcap-sanitize">$mailcap_sanitize</link> variable. 10773 </para> 10774 <para> 10775 Although NeoMutt's procedures to invoke programs with mailcap seem to 10776 be safe, there are other applications parsing mailcap, maybe taking 10777 less care of it. Therefore you should pay attention to the following 10778 rules: 10779 </para> 10780 <para> 10781 <emphasis>Keep the %-expandos away from shell quoting.</emphasis> 10782 Don't quote them with single or double quotes. NeoMutt does this for 10783 you, the right way, as should any other program which interprets 10784 mailcap. Don't put them into backtick expansions. Be highly careful 10785 with evil statements, and avoid them if possible at all. Trying to 10786 fix broken behavior with quotes introduces new leaks – there is no 10787 alternative to correct quoting in the first place. 10788 </para> 10789 <para> 10790 If you have to use the %-expandos' values in context where you need 10791 quoting or backtick expansions, put that value into a shell variable 10792 and reference the shell variable where necessary, as in the following 10793 example (using <literal>$charset</literal> inside the backtick 10794 expansion is safe, since it is not itself subject to any further 10795 expansion): 10796 </para> 10797 10798<screen> 10799text/test-mailcap-bug; cat %s; copiousoutput; test=charset=%{charset} \ 10800 && test "`echo $charset | tr '[A-Z]' '[a-z]'`" != iso-8859-1 10801</screen> 10802 10803 </sect2> 10804 10805 <sect2 id="advanced-mailcap"> 10806 <title>Advanced Mailcap Usage</title> 10807 10808 <sect3 id="optional-mailcap-fields"> 10809 <title>Optional Fields</title> 10810 <para> 10811 In addition to the required content-type and view command fields, 10812 you can add semi-colon <quote>;</quote> separated fields to set 10813 flags and other options. NeoMutt recognizes the following optional 10814 fields: 10815 </para> 10816 <variablelist> 10817 <varlistentry> 10818 <term>copiousoutput</term> 10819 <listitem> 10820 <para> 10821 This flag tells NeoMutt that the command passes possibly 10822 large amounts of text on standard output. This causes NeoMutt 10823 to invoke a pager (either the internal pager or the external 10824 pager defined by the pager variable) on the output of the 10825 view command. Without this flag, NeoMutt assumes that the 10826 command is interactive. One could use this to replace the 10827 pipe to <literal>more</literal> in the 10828 <literal>lynx -dump</literal> example in the Basic section: 10829 </para> 10830 <screen>text/html; lynx -dump %s ; copiousoutput</screen> 10831 <para> 10832 This will cause lynx to format the 10833 <literal>text/html</literal> output as 10834 <literal>text/plain</literal> and NeoMutt will use your 10835 standard pager to display the results. 10836 </para> 10837 <para> 10838 NeoMutt will set the <literal>COLUMNS</literal> environment 10839 variable to the width of the pager. Some programs make use of 10840 this environment variable automatically. Others provide 10841 a command line argument that can use this to set the output 10842 width: 10843 </para> 10844 10845<screen> 10846text/html; lynx -dump -width ${COLUMNS:-80} %s; copiousoutput 10847</screen> 10848 10849 <para> 10850 Note that when using the built-in pager, 10851 <emphasis>only</emphasis> entries with this flag will be 10852 considered a handler for a MIME type – all other entries will 10853 be ignored. 10854 </para> 10855 </listitem> 10856 </varlistentry> 10857 <varlistentry> 10858 <term>needsterminal</term> 10859 <listitem> 10860 <para> 10861 NeoMutt uses this flag when viewing attachments with 10862 <link linkend="auto-view"><command>auto_view</command></link>, 10863 in order to decide whether it should honor the setting of the 10864 <link linkend="wait-key">$wait_key</link> variable or not. 10865 When an attachment is viewed using an interactive program, 10866 and the corresponding mailcap entry has 10867 a <emphasis>needsterminal</emphasis> flag, NeoMutt will use 10868 <link linkend="wait-key">$wait_key</link> and the exit status 10869 of the program to decide if it will ask you to press a key 10870 after the external program has exited. In all other 10871 situations it will not prompt you for a key. 10872 </para> 10873 </listitem> 10874 </varlistentry> 10875 <varlistentry> 10876 <term>compose=<command></term> 10877 <listitem> 10878 <para> 10879 This flag specifies the command to use to create a new 10880 attachment of a specific MIME type. NeoMutt supports this 10881 from the compose menu. 10882 </para> 10883 </listitem> 10884 </varlistentry> 10885 <varlistentry> 10886 <term>composetyped=<command></term> 10887 <listitem> 10888 <para> 10889 This flag specifies the command to use to create a new 10890 attachment of a specific MIME type. This command differs from 10891 the compose command in that NeoMutt will expect standard MIME 10892 headers on the data. This can be used to specify parameters, 10893 filename, description, etc. for a new attachment. NeoMutt 10894 supports this from the compose menu. 10895 </para> 10896 </listitem> 10897 </varlistentry> 10898 <varlistentry> 10899 <term>print=<command></term> 10900 <listitem> 10901 <para> 10902 This flag specifies the command to use to print a specific 10903 MIME type. NeoMutt supports this from the attachment and 10904 compose menus. 10905 </para> 10906 </listitem> 10907 </varlistentry> 10908 <varlistentry> 10909 <term>edit=<command></term> 10910 <listitem> 10911 <para> 10912 This flag specifies the command to use to edit a specific 10913 MIME type. NeoMutt supports this from the compose menu, and 10914 also uses it to compose new attachments. NeoMutt will default 10915 to the defined <link linkend="editor">$editor</link> for text 10916 attachments. 10917 </para> 10918 </listitem> 10919 </varlistentry> 10920 <varlistentry> 10921 <term>nametemplate=<template></term> 10922 <listitem> 10923 <para> 10924 This field specifies the format for the file denoted by 10925 <literal>%s</literal> in the command fields. Certain programs 10926 will require a certain file extension, for instance, to 10927 correctly view a file. For instance, lynx will only interpret 10928 a file as <literal>text/html</literal> if the file ends in 10929 <literal>.html</literal>. So, you would specify lynx as 10930 a <literal>text/html</literal> viewer with a line in the 10931 mailcap file like: 10932 </para> 10933 <screen>text/html; lynx %s; nametemplate=%s.html</screen> 10934 </listitem> 10935 </varlistentry> 10936 <varlistentry> 10937 <term>test=<command></term> 10938 <listitem> 10939 <para> 10940 This field specifies a command to run to test whether this 10941 mailcap entry should be used. The command is defined with the 10942 command expansion rules defined in the next section. If the 10943 command returns 0, then the test passed, and NeoMutt uses 10944 this entry. If the command returns non-zero, then the test 10945 failed, and NeoMutt continues searching for the right entry. 10946 Note that the content-type must match before NeoMutt performs 10947 the test. For example: 10948 </para> 10949 10950<screen> 10951text/html; firefox -remote 'openURL(%s)' ; test=RunningX 10952text/html; lynx %s 10953</screen> 10954 10955 <para> 10956 In this example, NeoMutt will run the program 10957 <literal>RunningX</literal> which will return 0 if the 10958 X Window manager is running, and non-zero if it isn't. If 10959 <literal>RunningX</literal> returns 0, then NeoMutt will run 10960 firefox to display the <literal>text/html</literal> object. 10961 If RunningX doesn't return 0, then NeoMutt will go on to the 10962 next entry and use lynx to display the 10963 <literal>text/html</literal> object. 10964 </para> 10965 </listitem> 10966 </varlistentry> 10967 <varlistentry> 10968 <term>x-neomutt-keep</term> 10969 <listitem> 10970 <para> 10971 <literal>x-neomutt-keep</literal> tells NeoMutt to 10972 <emphasis>not</emphasis> delete the temporary file after the 10973 program has been run. 10974 </para> 10975 <para> 10976 Using it allows you to control the lifespan of the temporary 10977 file. Without this option, the file will be deleted after 10978 <link linkend="timeout">$timeout</link> seconds. 10979 </para> 10980 <screen>text/html; firefox %s & x-neomutt-keep</screen> 10981 </listitem> 10982 </varlistentry> 10983 <varlistentry> 10984 <term>x-neomutt-nowrap</term> 10985 <listitem> 10986 <para> 10987 <literal>x-neomutt-nowrap</literal> tells the NeoMutt pager 10988 to ignore the <link linkend="wrap">$wrap</link> parameter and 10989 to assume the output from the mailcap command to already be 10990 correctly wrapped. 10991 </para> 10992 <screen>text/html; /usr/local/bin/w3m -s -T text/html -o display_link_number=1 %s; nametemplate=%s.html; copiousoutput; x-neomutt-nowrap;</screen> 10993 </listitem> 10994 </varlistentry> 10995 </variablelist> 10996 </sect3> 10997 10998 <sect3 id="mailcap-search-order"> 10999 <title>Search Order</title> 11000 <para> 11001 When searching for an entry in the mailcap file, NeoMutt will 11002 search for the most useful entry for its purpose. For instance, if 11003 you are attempting to print an <literal>image/gif</literal>, and 11004 you have the following entries in your mailcap file, NeoMutt will 11005 search for an entry with the print command: 11006 </para> 11007 11008<screen> 11009image/*; xv %s 11010image/gif; ; print=anytopnm %s | pnmtops | lpr; \ 11011 nametemplate=%s.gif 11012</screen> 11013 11014 <para> 11015 NeoMutt will skip the <literal>image/*</literal> entry and use the 11016 <literal>image/gif</literal> entry with the print command. 11017 </para> 11018 <para> 11019 In addition, you can use this with 11020 <link linkend="auto-view"><command>auto_view</command></link> to 11021 denote two commands for viewing an attachment, one to be viewed 11022 automatically, the other to be viewed interactively from the 11023 attachment menu using the <literal><view-mailcap></literal> 11024 function (bound to <quote>m</quote> by default). In addition, you 11025 can then use the test feature to determine which viewer to use 11026 interactively depending on your environment. 11027 </para> 11028 11029<screen> 11030text/html; firefox -remote 'openURL(%s)' ; test=RunningX 11031text/html; lynx %s; nametemplate=%s.html 11032text/html; lynx -dump %s; nametemplate=%s.html; copiousoutput 11033</screen> 11034 11035 <para> 11036 For <link linkend="auto-view"><command>auto_view</command></link>, 11037 NeoMutt will choose the third entry because of the 11038 <literal>copiousoutput</literal> tag. For interactive viewing, 11039 NeoMutt will run the program <literal>RunningX</literal> to 11040 determine if it should use the first entry. If the program returns 11041 non-zero, NeoMutt will use the second entry for interactive 11042 viewing. The last entry is for inline display in the pager and the 11043 <literal><view-attach></literal> function in the attachment 11044 menu. 11045 </para> 11046 <para> 11047 Entries with the <literal>copiousoutput</literal> tag should always 11048 be specified as the last one per type. For non-interactive use, the 11049 last entry will then actually be the first matching one with the 11050 tag set. For non-interactive use, only 11051 <literal>copiousoutput</literal>-tagged entries are considered. For 11052 interactive use, NeoMutt ignores this tag and treats all entries 11053 equally. Therefore, if not specified last, all following entries 11054 without this tag would never be considered for 11055 <literal><view-attach></literal> because the 11056 <literal>copiousoutput</literal> before them matched already. 11057 </para> 11058 </sect3> 11059 11060 <sect3 id="mailcap-command-expansion"> 11061 <title>Command Expansion</title> 11062 <para> 11063 The various commands defined in the mailcap files are passed to the 11064 <literal>/bin/sh</literal> shell using the 11065 <literal>system(3)</literal> function. Before the command is passed 11066 to <literal>/bin/sh -c</literal>, it is parsed to expand various 11067 special parameters with information from NeoMutt. The keywords 11068 NeoMutt expands are: 11069 </para> 11070 <variablelist> 11071 <varlistentry> 11072 <term>%s</term> 11073 <listitem> 11074 <para> 11075 As seen in the basic mailcap section, this variable is 11076 expanded to a filename specified by the calling program. This 11077 file contains the body of the message to view/print/edit or 11078 where the composing program should place the results of 11079 composition. In addition, the use of this keyword causes 11080 NeoMutt to not pass the body of the message to the 11081 view/print/edit program on stdin. 11082 </para> 11083 </listitem> 11084 </varlistentry> 11085 <varlistentry> 11086 <term>%t</term> 11087 <listitem> 11088 <para> 11089 NeoMutt will expand <literal>%t</literal> to the text 11090 representation of the content type of the message in the same 11091 form as the first parameter of the mailcap definition line, 11092 i.e. <literal>text/html</literal> or 11093 <literal>image/gif</literal>. 11094 </para> 11095 </listitem> 11096 </varlistentry> 11097 <varlistentry> 11098 <term>%{<parameter>}</term> 11099 <listitem> 11100 <para> 11101 NeoMutt will expand this to the value of the specified 11102 parameter from the Content-Type: line of the mail message. 11103 For instance, if your mail message contains: 11104 </para> 11105 <screen>Content-Type: text/plain; charset=iso-8859-1</screen> 11106 <para> 11107 then NeoMutt will expand <literal>%{charset}</literal> to 11108 <quote>iso-8859-1</quote>. The default metamail mailcap file 11109 uses this feature to test the charset to spawn an xterm using 11110 the right charset to view the message. 11111 </para> 11112 </listitem> 11113 </varlistentry> 11114 <varlistentry> 11115 <term>\%</term> 11116 <listitem> 11117 <para> 11118 This will be replaced by a literal <literal>%</literal>. 11119 </para> 11120 </listitem> 11121 </varlistentry> 11122 </variablelist> 11123 <para> 11124 NeoMutt does not currently support the <literal>%F</literal> and 11125 <literal>%n</literal> keywords specified in RFC1524. The main 11126 purpose of these parameters is for multipart messages, which is 11127 handled internally by NeoMutt. 11128 </para> 11129 </sect3> 11130 </sect2> 11131 11132 <sect2 id="mailcap-example"> 11133 <title>Example Mailcap Files</title> 11134 <para> 11135 This mailcap file is fairly simple and standard: 11136 </para> 11137 11138<screen> 11139<emphasis role="comment"># I'm always running X :)</emphasis> 11140video/*; xanim %s > /dev/null 11141image/*; xv %s > /dev/null 11142<emphasis role="comment"># I'm always running firefox (if my computer had more memory, maybe)</emphasis> 11143text/html; firefox -remote 'openURL(%s)' 11144</screen> 11145 11146 <para> 11147 These mailcap files shows how to control the lifespan of the temporary file. 11148 </para> 11149 11150<screen> 11151<emphasis role="comment"># The `display` program shows an image and doesn't return until the user quits.</emphasis> 11152 11153<emphasis role="comment"># Display an image, but wait for the user to quit the display program.</emphasis> 11154<emphasis role="comment"># When the user quits control will return to NeoMutt.</emphasis> 11155image/png; display %s; 11156 11157<emphasis role="comment"># Display an image and return to NeoMutt immediately.</emphasis> 11158image/png; display %s &; 11159 11160<emphasis role="comment"># The file will be automatically deleted after $timeout seconds.</emphasis> 11161</screen> 11162 11163<screen> 11164<emphasis role="comment"># Some graphical programs return immediately if they're already running.</emphasis> 11165<emphasis role="comment"># We'll add an ampersand (&), just in case they're not.</emphasis> 11166 11167<emphasis role="comment"># View the contents of a 'tar' file.</emphasis> 11168<emphasis role="comment"># The file will be automatically deleted after $timeout seconds.</emphasis> 11169application/x-tar; file-roller %s &; 11170 11171<emphasis role="comment"># View the contents of a 'tar' file.</emphasis> 11172<emphasis role="comment"># The file will <emphasis>not</emphasis> be deleted.</emphasis> 11173application/x-tar; file-roller %s &; x-neomutt-keep 11174</screen> 11175 11176<screen> 11177<emphasis role="comment"># Some programs watch any files they have open.</emphasis> 11178<emphasis role="comment"># If NeoMutt deleted the file, the program would close prematurely.</emphasis> 11179 11180<emphasis role="comment"># Use a custom script to manage the file's lifespan.</emphasis> 11181application/pdf; my-pdf-script.sh %s; x-neomutt-keep 11182</screen> 11183 11184 <para> 11185 This mailcap file shows quite a number of examples: 11186 </para> 11187 11188<screen> 11189<emphasis role="comment"># Use xanim to view all videos Xanim produces a header on startup,</emphasis> 11190<emphasis role="comment"># send that to /dev/null so I don't see it</emphasis> 11191video/*; xanim %s > /dev/null 11192<emphasis role="comment"># Send html to a running firefox by remote</emphasis> 11193text/html; firefox -remote 'openURL(%s)'; test=RunningFirefox 11194<emphasis role="comment"># If I'm not running firefox but I am running X, start firefox on the</emphasis> 11195<emphasis role="comment"># object</emphasis> 11196text/html; firefox %s; test=RunningX 11197<emphasis role="comment"># Else use lynx to view it as text</emphasis> 11198text/html; lynx %s 11199<emphasis role="comment"># This version would convert the text/html to text/plain</emphasis> 11200text/html; lynx -dump %s; copiousoutput 11201<emphasis role="comment"># I use enscript to print text in two columns to a page</emphasis> 11202text/*; more %s; print=enscript -2Gr %s 11203<emphasis role="comment"># Firefox adds a flag to tell itself to view jpegs internally</emphasis> 11204image/jpeg; xv %s; x-mozilla-flags=internal 11205<emphasis role="comment"># Use xv to view images if I'm running X</emphasis> 11206<emphasis role="comment"># In addition, this uses the \ to extend the line and set my editor</emphasis> 11207<emphasis role="comment"># for images</emphasis> 11208image/*; xv %s; test=RunningX; edit=xpaint %s 11209<emphasis role="comment"># Convert images to text using the netpbm tools</emphasis> 11210image/*; (anytopnm %s | pnmscale -xysize 80 46 | ppmtopgm | pgmtopbm | \ 11211 pbmtoascii -1x2) 2>&1 ; copiousoutput 11212<emphasis role="comment"># Send excel spreadsheets to my NT box</emphasis> 11213application/ms-excel; open.pl %s 11214</screen> 11215 11216 </sect2> 11217 </sect1> 11218 11219 <sect1 id="auto-view"> 11220 <title>MIME Autoview</title> 11221 <para> 11222 Usage: 11223 </para> 11224 <cmdsynopsis> 11225 <command>auto_view</command> 11226 <arg choice="plain"> 11227 <replaceable>mime-type</replaceable> 11228 </arg> 11229 <arg choice="opt"> 11230 <replaceable>/mime-subtype</replaceable> 11231 </arg> 11232 <arg choice="opt" rep="repeat"> 11233 <arg choice="plain"> 11234 <replaceable>mime-type</replaceable> 11235 </arg> 11236 <arg choice="opt"> 11237 <replaceable>/mime-subtype</replaceable> 11238 </arg> 11239 </arg> 11240 <command>unauto_view</command> 11241 <group choice="req"> 11242 <arg choice="plain">*</arg> 11243 <arg choice="opt" rep="repeat"> 11244 <arg choice="plain"> 11245 <replaceable>mime-type</replaceable> 11246 </arg> 11247 <arg choice="opt"> 11248 <replaceable>/mime-subtype</replaceable> 11249 </arg> 11250 </arg> 11251 </group> 11252 </cmdsynopsis> 11253 <para> 11254 In addition to explicitly telling NeoMutt to view an attachment with 11255 the MIME viewer defined in the mailcap file from the attachments menu, 11256 NeoMutt has support for automatically viewing MIME attachments while in 11257 the pager. 11258 </para> 11259 <para> 11260 For this to work, you must define a viewer in the mailcap file which 11261 uses the <literal>copiousoutput</literal> option to denote that it is 11262 non-interactive. Usually, you also use the entry to convert the 11263 attachment to a text representation which you can view in the pager. 11264 </para> 11265 <para> 11266 You then use the <command>auto_view</command> configuration command to 11267 list the content-types that you wish to view automatically. For 11268 instance, if you set it to: 11269 </para> 11270 11271<screen> 11272auto_view text/html application/x-gunzip \ 11273 application/postscript image/gif application/x-tar-gz 11274</screen> 11275 11276 <para> 11277 ...NeoMutt would try to find corresponding entries for rendering 11278 attachments of these types as text. A corresponding mailcap could look 11279 like: 11280 </para> 11281 11282<screen> 11283text/html; lynx -dump %s; copiousoutput; nametemplate=%s.html 11284image/*; anytopnm %s | pnmscale -xsize 80 -ysize 50 | ppmtopgm | \ 11285 pgmtopbm | pbmtoascii ; copiousoutput 11286application/x-gunzip; gzcat; copiousoutput 11287application/x-tar-gz; gunzip -c %s | tar -tf - ; copiousoutput 11288application/postscript; ps2ascii %s; copiousoutput 11289</screen> 11290 11291 <para> 11292 <command>unauto_view</command> can be used to remove previous entries 11293 from the <command>auto_view</command> list. This can be used with 11294 <link linkend="message-hook"><command>message-hook</command></link> to 11295 autoview messages based on size, etc. 11296 <quote><command>unauto_view</command> *</quote> will remove all 11297 previous entries. 11298 </para> 11299 </sect1> 11300 11301 <sect1 id="alternative-order"> 11302 <title>MIME Multipart/Alternative</title> 11303 11304 <para> 11305 A <literal>multipart/alternative</literal> email has several 11306 parts that represent the same content in different formats, such as 11307 <literal>text/plain</literal> and <literal>text/html</literal>. This 11308 kind of email is heavily used by many modern mail user agents to send 11309 HTML messages which contain an alternative plain text representation. 11310 You can read and write <literal>multipart/alternative</literal> emails 11311 in NeoMutt. 11312 </para> 11313 11314 <sect2 id="read-alternative-order"> 11315 <title>Reading Multipart/Alternative Emails</title> 11316 <para> 11317 NeoMutt has some heuristics for determining which attachment of 11318 a <literal>multipart/alternative</literal> type to display: 11319 </para> 11320 <orderedlist> 11321 <listitem> 11322 <para> 11323 First, NeoMutt will check the <command>alternative_order</command> 11324 list to determine if one of the available types is preferred. It 11325 consists of a number of MIME types in order, including support for 11326 implicit and explicit wildcards. For example: 11327 </para> 11328 11329<screen> 11330alternative_order text/enriched text/plain text application/postscript image/* 11331</screen> 11332 11333 </listitem> 11334 <listitem> 11335 <para> 11336 Next, NeoMutt will check if any of the types have a defined 11337 <link linkend="auto-view"><command>auto_view</command></link>, and 11338 use that. 11339 </para> 11340 </listitem> 11341 <listitem> 11342 <para> 11343 Failing that, NeoMutt will look for any text type. 11344 </para> 11345 </listitem> 11346 <listitem> 11347 <para> 11348 As a last attempt, NeoMutt will look for any type it knows how to 11349 handle. 11350 </para> 11351 </listitem> 11352 </orderedlist> 11353 <para> 11354 To remove a MIME type from the <command>alternative_order</command> 11355 list, use the <command>unalternative_order</command> command. 11356 </para> 11357 </sect2> 11358 11359 <sect2 id="compose-alternative-order"> 11360 <title>Composing Multipart/Alternative Emails</title> 11361 11362 <para> 11363 Noemutt includes some primitive ability to compose multipart/alternative 11364 emails: 11365 </para> 11366 <orderedlist> 11367 <listitem> 11368 <para> 11369 In the Compose menu, attach the two (or more) alternatives as 11370 usual. For example, attach "invitation.html" and then "invitation.txt". 11371 (You can reorder them using the <literal><move-up></literal> (-) 11372 and <literal><move-down></literal> (+) bindings, and edit the 11373 descriptions). 11374 </para> 11375 </listitem> 11376 <listitem> 11377 <para> 11378 Tag the attachments that are alternatives, and press the 11379 <command><group-alternatives></command> (&) binding to group 11380 them together. After this, the separate parts will be replaced by a single 11381 new part with the <literal>multipart/alternative</literal> type and the 11382 alternatives must be manipulated or deleted as a group. 11383 </para> 11384 </listitem> 11385 <listitem> 11386 <para> 11387 Send the email as usual. 11388 </para> 11389 </listitem> 11390 </orderedlist> 11391 <para> 11392 If all the attachments have been grouped and form a single 11393 <literal>multipart/alternative</literal>, part then this message will be sent 11394 as a <literal>multipart/alternative</literal> email, otherwise it will be sent 11395 as a <literal>multipart/mixed</literal> email. 11396 </para> 11397 <para> 11398 Note that after grouping, you can't view, edit or break the 11399 <literal>multipart/alternative</literal> bundle, because it is in a temporary 11400 form. But you can view and edit its primitive part using the 11401 <command><edit></command> command. When postponing emails or on error 11402 (e.g., no recipients address when sending emails) this 11403 <literal>multipart/alternative</literal> will be broken apart and need to 11404 be tagged and group together again as described above. 11405 </para> 11406 11407 <para> 11408 Be aware that when sending a <literal>multipart/alternative</literal> email, 11409 you have to manually prepare the alternative parts and attach them. However, 11410 you can use Neomutt's macro to perform all the operations needed, such that 11411 you can compose a plain text email as usual and turn that into a 11412 <literal>multipart/alternative</literal> email in one single command, with 11413 one part being <literal>text/plain</literal> and the other 11414 <literal>text/html</literal>. An example macro will be the following: 11415 11416<screen> 11417macro compose K "| pandoc -o /tmp/neomutt-alternative.html<enter> \ 11418 <attach-file>/tmp/neomutt-alternative.html<enter> \ 11419 <tag-entry><previous-entry><tag-entry><group-alternatives>" 11420</screen> 11421 </para> 11422 </sect2> 11423 </sect1> 11424 11425 <sect1 id="multipart-multilingual"> 11426 <title>MIME Multipart/Multilingual</title> 11427 11428 <para> 11429 Neomutt includes supports for reading and writing <literal>multipart/multilingual</literal> 11430 emails. A <literal>multipart/multilingual</literal> email is like a 11431 <literal>multipart/alternative</literal> email, except that it comes with parts of 11432 different versions of languages instead of appearances. Its format is described by 11433 <ulink url="https://tools.ietf.org/html/rfc8255">RFC8255</ulink>. 11434 </para> 11435 11436 <sect2 id="read-multipart-multilingual"> 11437 <title>Reading Multipart/Multilingual Emails</title> 11438 <para> 11439 Neomutt uses the <literal>$preferred_languages</literal> variable to determine which 11440 languages to display when displaying a <literal>multipart/multilingual</literal> email. 11441 You can have several preferred languages, separated by <literal>,</literal> 11442<screen> 11443set preferred_languages="fr,en,de" 11444</screen> 11445 Neomutt will try to match these strings again the multilingual header in the received 11446 emails "by prefix", e.g., <literal>en</literal> will match both <literal>en</literal> 11447 and <literal>en_US</literal>. 11448 </para> 11449 11450 <para> 11451 If <literal>$preferred_languages</literal> is not set, it default to None, and the 11452 first part of the received <literal>multipart/multilingual</literal> email will be 11453 displayed. 11454 </para> 11455 </sect2> 11456 11457 <sect2 id="compose-multipart-alternative"> 11458 <title>Composing Multipart/Multilingual Emails</title> 11459 <para> 11460 The procedures of composing a <literal>multipart/multilingual</literal> email is similar 11461 to those in <link linkend="compose-alternative-order">Composing Multipart/Alternative</link>. 11462 You have to prepare every part manually or using some scripts, and then tag and group them 11463 together into a <literal>multipart/multilingual</literal> bundle before sending it: 11464 </para> 11465 11466 <orderedlist> 11467 <listitem> 11468 <para> 11469 Prepare parts of the multilingual emails. 11470 </para> 11471 </listitem> 11472 11473 <listitem> 11474 <para> 11475 Attach them as attachments. 11476 </para> 11477 </listitem> 11478 11479 <listitem> 11480 <para> 11481 Tag them with <command><tag-entry></command> 11482 </para> 11483 </listitem> 11484 11485 <listitem> 11486 <para> 11487 Edit the <literal>Content-Language</literal> header of every attachment with command 11488 <command><edit-language></command> (default to <literal>Ctrl-L</literal>). This 11489 is important, otherwise the recipient of this email will not know the corresponding 11490 languages. You can set arbitrary string as <literal>Content-Language</literal>, but it 11491 is recommended to set it as some common prefixes such as "en", "zh" and "fr". 11492 </para> 11493 </listitem> 11494 <listitem> 11495 <para> 11496 Group all the tag messages together by <command><group-multilingual></command> 11497 (default to <literal>^</literal>). 11498 </para> 11499 </listitem> 11500 <listitem> 11501 <para> 11502 Send the email as usual. 11503 </para> 11504 </listitem> 11505 11506 </orderedlist> 11507 11508 <para> 11509 As in <link linkend="compose-alternative-order">Composing Multipart/Alternative</link>, you can 11510 also use Neomutt's macro and some external scripts to combine these procedure into one. 11511 </para> 11512 11513 <para> 11514 Note that after grouping, you can't view, edit or break the 11515 <literal>multipart/multilingual</literal> email bundle, because it is in a temporary form. 11516 But you can view and edit its primitive part using the <command><edit></command> 11517 command. When postponing emails or on error (e.g., no recipients address when sending 11518 emails) this <literal>multipart/multilingual</literal> will be broken apart and need to 11519 be tagged and group together again as described above. 11520 </para> 11521 </sect2> 11522 </sect1> 11523 11524 <sect1 id="attachments"> 11525 <title>Attachment Searching and Counting</title> 11526 <para> 11527 If you ever lose track of attachments in your mailboxes, NeoMutt's 11528 attachment-counting and -searching support might be for you. You can 11529 make your message index display the number of qualifying attachments in 11530 each message, or search for messages by attachment count. You also can 11531 configure what kinds of attachments qualify for this feature with the 11532 <command>attachments</command> and <command>unattachments</command> 11533 commands. 11534 </para> 11535 <para> 11536 In order to provide this information, NeoMutt needs to fully MIME-parse 11537 all messages affected first. This can slow down operation especially 11538 for remote mail folders such as IMAP because all messages have to be 11539 downloaded first regardless whether the user really wants to view them 11540 or not though using <xref linkend="body-caching" /> usually means to 11541 download the message just once. 11542 </para> 11543 <para> 11544 By default, Mutt will not search inside 11545 <literal>multipart/alternative</literal> containers. This can be changed 11546 via the <link linkend="count-alternatives">$count_alternatives</link> 11547 configuration variable. 11548 </para> 11549 <para> 11550 The syntax is: 11551 </para> 11552 <cmdsynopsis> 11553 <command>attachments</command> 11554 <group choice="req"> 11555 <arg choice="plain">+</arg> 11556 <arg choice="plain">-</arg> 11557 </group> 11558 <arg choice="plain"> 11559 <replaceable>disposition</replaceable> 11560 </arg> 11561 <arg choice="plain"> 11562 <replaceable>mime-type</replaceable> 11563 </arg> 11564 <command>unattachments</command> 11565 <group choice="req"> 11566 <arg choice="plain">+</arg> 11567 <arg choice="plain">-</arg> 11568 </group> 11569 <arg choice="plain"> 11570 <replaceable>disposition</replaceable> 11571 </arg> 11572 <arg choice="plain"> 11573 <replaceable>mime-type</replaceable> 11574 </arg> 11575 <command>attachments</command> 11576 <arg choice="plain"> 11577 <option>?</option> 11578 </arg> 11579 <command>unattachments</command> 11580 <arg choice="plain"> 11581 <option>*</option> 11582 </arg> 11583 </cmdsynopsis> 11584 <para> 11585 <emphasis>disposition</emphasis> is the attachment's 11586 Content-Disposition type – either <literal>inline</literal> or 11587 <literal>attachment</literal>. You can abbreviate this to 11588 <literal>I</literal> or <literal>A</literal>. 11589 </para> 11590 <para> 11591 Disposition is prefixed by either a <quote>+</quote> symbol or 11592 a <quote>-</quote> symbol. If it's a <quote>+</quote>, you're saying 11593 that you want to allow this disposition and MIME type to qualify. If 11594 it's a <quote>-</quote>, you're saying that this disposition and MIME 11595 type is an exception to previous <quote>+</quote> rules. There are 11596 examples below of how this is useful. 11597 </para> 11598 <para> 11599 <emphasis>mime-type</emphasis> is the MIME type of the attachment you 11600 want the command to affect. A MIME type is always of the format 11601 <literal>major/minor</literal>, where <literal>major</literal> 11602 describes the broad category of document you're looking at, and 11603 <literal>minor</literal> describes the specific type within that 11604 category. The major part of mime-type must be literal text (or the 11605 special token <quote><literal>*</literal></quote>), but the minor 11606 part may be a regular expression. (Therefore, 11607 <quote><literal>*/.*</literal></quote> matches any MIME type.) 11608 </para> 11609 <para> 11610 The MIME types you give to the <command>attachments</command> directive 11611 are a kind of pattern. When you use the <command>attachments</command> 11612 directive, the patterns you specify are added to a list. When you use 11613 <command>unattachments</command>, the pattern is removed from the list. 11614 The patterns are not expanded and matched to specific MIME types at 11615 this time – they're just text in a list. They're only matched when 11616 actually evaluating a message. 11617 </para> 11618 <para> 11619 Some examples might help to illustrate. The examples that are not 11620 commented out define the default configuration of the lists. 11621 </para> 11622 <example id="ex-attach-count"> 11623 <title>Attachment counting</title> 11624 11625<screen> 11626<emphasis role="comment"># Removing a pattern from a list removes that pattern literally. It</emphasis> 11627<emphasis role="comment"># does not remove any type matching the pattern.</emphasis> 11628<emphasis role="comment">#</emphasis> 11629<emphasis role="comment"># attachments +A */.*</emphasis> 11630<emphasis role="comment"># attachments +A image/jpeg</emphasis> 11631<emphasis role="comment"># unattachments +A */.*</emphasis> 11632<emphasis role="comment">#</emphasis> 11633<emphasis role="comment"># This leaves "attached" image/jpeg files on the allowed attachments</emphasis> 11634<emphasis role="comment"># list. It does not remove all items, as you might expect, because the</emphasis> 11635<emphasis role="comment"># second */.* is not a matching expression at this time.</emphasis> 11636<emphasis role="comment">#</emphasis> 11637<emphasis role="comment"># Remember: "unattachments" only undoes what "attachments" has done!</emphasis> 11638<emphasis role="comment"># It does not trigger any matching on actual messages.</emphasis> 11639<emphasis role="comment"># Qualify any MIME part with an "attachment" disposition, EXCEPT for</emphasis> 11640<emphasis role="comment"># text/x-vcard and application/pgp parts. (PGP parts are already known</emphasis> 11641<emphasis role="comment"># to NeoMutt, and can be searched for with ~g, ~G, and ~k.)</emphasis> 11642<emphasis role="comment">#</emphasis> 11643<emphasis role="comment"># I've added x-pkcs7 to this, since it functions (for S/MIME)</emphasis> 11644<emphasis role="comment"># analogously to PGP signature attachments. S/MIME isn't supported</emphasis> 11645<emphasis role="comment"># in a stock NeoMutt build, but we can still treat it specially here.</emphasis> 11646<emphasis role="comment">#</emphasis> 11647attachments +A */.* 11648attachments -A text/x-vcard application/pgp.* 11649attachments -A application/x-pkcs7-.* 11650<emphasis role="comment"># Discount all MIME parts with an "inline" disposition, unless they're</emphasis> 11651<emphasis role="comment"># text/plain. (Why inline a text/plain part unless it's external to the</emphasis> 11652<emphasis role="comment"># message flow?)</emphasis> 11653attachments +I text/plain 11654<emphasis role="comment"># These two lines make NeoMutt qualify MIME containers. (So, for example,</emphasis> 11655<emphasis role="comment"># a message/rfc822 forward will count as an attachment.) The first</emphasis> 11656<emphasis role="comment"># line is unnecessary if you already have "attach-allow */.*", of</emphasis> 11657<emphasis role="comment"># course. These are off by default! The MIME elements contained</emphasis> 11658<emphasis role="comment"># within a message/* or multipart/* are still examined, even if the</emphasis> 11659<emphasis role="comment"># containers themselves don't qualify.</emphasis> 11660<emphasis role="comment"># Recursion into multipart/alternatives containers is controlled by the</emphasis> 11661<emphasis role="comment"># $count_alternatives setting.</emphasis> 11662 11663<emphasis role="comment">#attachments +A message/.* multipart/.*</emphasis> 11664<emphasis role="comment">#attachments +I message/.* multipart/.*</emphasis> 11665<emphasis role="comment">## You probably don't really care to know about deleted attachments.</emphasis> 11666attachments -A message/external-body 11667attachments -I message/external-body 11668</screen> 11669 11670 </example> 11671 <para> 11672 Entering the command <quote><command>attachments</command> ?</quote> as 11673 a command will list your current settings in neomuttrc format, so that 11674 it can be pasted elsewhere. 11675 </para> 11676 11677 <para> 11678 Entering the command <quote><command>unattachments</command> *</quote> 11679 as a command will Clear all attachment settings. 11680 </para> 11681 </sect1> 11682 11683 <sect1 id="mime-lookup"> 11684 <title>MIME Lookup</title> 11685 <para> 11686 Usage: 11687 </para> 11688 <cmdsynopsis> 11689 <command>mime_lookup</command> 11690 <arg choice="plain"> 11691 <replaceable>mime-type</replaceable> 11692 </arg> 11693 <arg choice="opt"> 11694 <replaceable>/mime-subtype</replaceable> 11695 </arg> 11696 <arg choice="opt" rep="repeat"> 11697 <arg choice="plain"> 11698 <replaceable>mime-type</replaceable> 11699 </arg> 11700 <arg choice="opt"> 11701 <replaceable>/mime-subtype</replaceable> 11702 </arg> 11703 </arg> 11704 <command>unmime_lookup</command> 11705 <group choice="req"> 11706 <arg choice="plain">*</arg> 11707 <arg choice="opt" rep="repeat"> 11708 <arg choice="plain"> 11709 <replaceable>mime-type</replaceable> 11710 </arg> 11711 <arg choice="opt"> 11712 <replaceable>/mime-subtype</replaceable> 11713 </arg> 11714 </arg> 11715 </group> 11716 </cmdsynopsis> 11717 <para> 11718 NeoMutt's <command>mime_lookup</command> list specifies a list of MIME 11719 types that should <emphasis>not</emphasis> be treated according to 11720 their mailcap entry. This option is designed to deal with binary types 11721 such as <literal>application/octet-stream</literal>. When an 11722 attachment's MIME type is listed in <command>mime_lookup</command>, 11723 then the extension of the filename will be compared to the list of 11724 extensions in the <literal>mime.types</literal> file. The MIME type 11725 associated with this extension will then be used to process the 11726 attachment according to the rules in the mailcap file and according to 11727 any other configuration options (such as <command>auto_view</command>) 11728 specified. Common usage would be: 11729 </para> 11730 11731<screen> 11732mime_lookup application/octet-stream application/X-Lotus-Manuscript 11733</screen> 11734 11735 <para> 11736 In addition, the <literal>unmime_lookup</literal> command may be used 11737 to disable this feature for any particular MIME type if it had been 11738 set, for example, in a global <literal>.neomuttrc</literal>. 11739 </para> 11740 </sect1> 11741 </chapter> 11742 11743 <chapter id="optionalfeatures"> 11744 <title>Optional Features</title> 11745 11746 <sect1 id="optionalfeatures-notes"> 11747 <title>General Notes</title> 11748 11749 <sect2 id="compile-time-features"> 11750 <title>Enabling/Disabling Features</title> 11751 <para> 11752 NeoMutt supports several of optional features which can be enabled or 11753 disabled at compile-time by giving the <emphasis>configure</emphasis> 11754 script certain arguments. These are listed in the 11755 <quote>Optional features</quote> section of the 11756 <emphasis>configure --help</emphasis> output. 11757 </para> 11758 <para> 11759 Which features are enabled or disabled can later be determined from 11760 the output of <literal>neomutt -v</literal>. If a compile option 11761 starts with <quote>+</quote> it is enabled and disabled if prefixed 11762 with <quote>-</quote>. For example, if NeoMutt was compiled using 11763 GnuTLS for encrypted communication instead of OpenSSL, 11764 <literal>neomutt -v</literal> would contain: 11765 </para> 11766 <screen>-openssl +gnutls</screen> 11767 </sect2> 11768 11769 <sect2 id="url-syntax"> 11770 <title>URL Syntax</title> 11771 <para> 11772 NeoMutt optionally supports the IMAP, POP3 and SMTP protocols which 11773 require to access servers using URLs. The canonical syntax for 11774 specifying URLs in NeoMutt is (an item enclosed in 11775 <literal>[]</literal> means it is optional and may be omitted): 11776 </para> 11777 <screen>proto[s]://[username[:password]@]server[:port][/path]</screen> 11778 <para> 11779 <emphasis>proto</emphasis> is the communication protocol: 11780 <literal>imap</literal> for IMAP, <literal>pop</literal> for POP3 and 11781 <literal>smtp</literal> for SMTP. If <quote>s</quote> for 11782 <quote>secure communication</quote> is appended, NeoMutt will attempt 11783 to establish an encrypted communication using SSL or TLS. 11784 </para> 11785 <para> 11786 Since all protocols supported by NeoMutt support/require 11787 authentication, login credentials may be specified in the URL. This 11788 has the advantage that multiple IMAP, POP3 or SMTP servers may be 11789 specified (which isn't possible using, for example, 11790 <link linkend="imap-user">$imap_user</link>). The username may contain 11791 the <quote>@</quote> symbol being used by many mail systems as part 11792 of the login name. The special characters <quote>/</quote> 11793 (<literal>%2F</literal>), <quote>:</quote> (<literal>%3A</literal>) 11794 and <quote>%</quote> (<literal>%25</literal>) have to be URL-encoded 11795 in usernames using the <literal>%</literal>-notation. 11796 </para> 11797 <para> 11798 A password can be given, too but is not recommended if the URL is 11799 specified in a configuration file on disk. 11800 </para> 11801 <para> 11802 If no port number is given, NeoMutt will use the system's default for 11803 the given protocol (usually consulting 11804 <literal>/etc/services</literal>). 11805 </para> 11806 <para> 11807 The optional path is only relevant for IMAP and ignored elsewhere. 11808 </para> 11809 <example id="ex-url"> 11810 <title>URLs</title> 11811 11812<screen> 11813pops://host/ 11814imaps://user@host/INBOX/Sent 11815smtp://user@host:587/ 11816</screen> 11817 11818 </example> 11819 </sect2> 11820 </sect1> 11821 11822 <sect1 id="ssl"> 11823 <title>SSL/TLS Support</title> 11824 <para> 11825 If NeoMutt is compiled with IMAP, POP3 and/or SMTP support, it can also 11826 be compiled with support for SSL or TLS using either OpenSSL or GnuTLS 11827 (by running the <emphasis>configure</emphasis> script with the 11828 <emphasis>--ssl=...</emphasis> option for OpenSSL or 11829 <emphasis>--gnutls=...</emphasis> for GnuTLS). NeoMutt can then 11830 attempt to encrypt communication with remote servers if these protocols 11831 are suffixed with <quote>s</quote> for 11832 <quote>secure communication</quote>. 11833 </para> 11834 11835 <sect2 id="starttls"> 11836 <title>STARTTLS</title> 11837 <para> 11838 When non-secure URL protocols <literal>imap://</literal>, 11839 <literal>pop://</literal>, and <literal>smtp://</literal> are 11840 used, the initial connection to the server will be unencrypted. 11841 <literal>STARTTLS</literal> can be used to negotiate an encrypted 11842 connection after the initial unencrypted connection and exchange. 11843 </para> 11844 <para> 11845 Two configuration variables control NeoMutt's behavior with 11846 <literal>STARTTLS</literal>. <link 11847 linkend="ssl-starttls">$ssl_starttls</link> will initiate 11848 <literal>STARTTLS</literal> if the server advertises support for 11849 it. <link linkend="ssl-force-tls">$ssl_force_tls</link> will 11850 always try to initiate it, whether the server advertises support 11851 or not. 11852 </para> 11853 <para> 11854 NeoMutt <emphasis>highly recommends</emphasis> setting <link 11855 linkend="ssl-force-tls">$ssl_force_tls</link> unless you need to 11856 connect to an unencrypted server. It's possible for an attacker 11857 to spoof interactions during the initial connection and hide 11858 support for <literal>STARTTLS</literal>. The only way to prevent 11859 these attacks is by forcing <literal>STARTTLS</literal> with the 11860 <link linkend="ssl-force-tls">$ssl_force_tls</link> configuration 11861 variable. 11862 </para> 11863 </sect2> 11864 11865 <sect2 id="secure-tunnel"> 11866 <title>Tunnel</title> 11867 <para> 11868 When connecting through a <link linkend="tunnel">$tunnel</link> 11869 and <link linkend="tunnel-is-secure">$tunnel_is_secure</link> is 11870 set(the default), NeoMutt will assume the connection to the server 11871 through the pipe is already secured. NeoMutt will ignore <link 11872 linkend="ssl-starttls">$ssl_starttls</link> and <link 11873 linkend="ssl-force-tls">$ssl_force_tls</link>, behaving as if TLS 11874 has already been negotiated. 11875 </para> 11876 <para> 11877 When <link linkend="tunnel-is-secure">$tunnel_is_secure</link> is 11878 unset, NeoMutt will respect the values of <link 11879 linkend="ssl-starttls">$ssl_starttls</link> and <link 11880 linkend="ssl-force-tls">$ssl_force_tls</link>. It is 11881 <emphasis>highly recommended</emphasis> to set <link 11882 linkend="ssl-force-tls">$ssl_force_tls</link> in this case, to 11883 force <literal>STARTTLS</literal> negotiation. Note that doing so 11884 will prevent connection to an IMAP server configured for 11885 preauthentication(<literal>PREAUTH</literal>). If you use this 11886 configuration, it is recommended to use a secure tunnel. 11887 </para> 11888 </sect2> 11889 11890 </sect1> 11891 11892 <sect1 id="pop"> 11893 <title>POP3 Support</title> 11894 <para> 11895 NeoMutt has POP3 support and has the ability to work with mailboxes 11896 located on a remote POP3 server and fetch mail for local browsing. 11897 </para> 11898 <para> 11899 Remote POP3 servers can be accessed using URLs with the 11900 <literal>pop</literal> protocol for unencrypted and 11901 <literal>pops</literal> for encrypted communication, see 11902 <xref linkend="url-syntax" /> for details. 11903 </para> 11904 <para> 11905 Polling for new mail is more expensive over POP3 than locally. For this 11906 reason the frequency at which NeoMutt will check for mail remotely can 11907 be controlled by the 11908 <link linkend="pop-check-interval">$pop_check_interval</link> variable, 11909 which defaults to every 60 seconds. 11910 </para> 11911 <para> 11912 POP is read-only which doesn't allow for some features like editing 11913 messages or changing flags. However, using 11914 <xref linkend="header-caching" /> and <xref linkend="body-caching" /> 11915 NeoMutt simulates the new/old/read flags as well as flagged and 11916 replied. NeoMutt applies some logic on top of remote messages but 11917 cannot change them so that modifications of flags are lost when 11918 messages are downloaded from the POP server (either by NeoMutt or other 11919 tools). 11920 </para> 11921 <anchor id="fetch-mail" /> 11922 <para> 11923 Another way to access your POP3 mail is the 11924 <literal><fetch-mail></literal> function (default: G). It allows 11925 to connect to <link linkend="pop-host">$pop_host</link>, fetch all your 11926 new mail and place it in the local 11927 <link linkend="spool-file">$spool_file</link>. After this point, NeoMutt 11928 runs exactly as if the mail had always been local. 11929 </para> 11930 <note> 11931 <para> 11932 If you only need to fetch all messages to a local mailbox you should 11933 consider using a specialized program, such as 11934 <literal>fetchmail(1)</literal>, <literal>getmail(1)</literal> or 11935 similar. 11936 </para> 11937 </note> 11938 </sect1> 11939 11940 <sect1 id="imap"> 11941 <title>IMAP Support</title> 11942 <para> 11943 NeoMutt has IMAP support and has the ability to work with folders 11944 located on a remote IMAP server. 11945 </para> 11946 <para> 11947 You can access the remote inbox by selecting the folder by its URL (see 11948 <xref linkend="url-syntax" /> for details) using the 11949 <literal>imap</literal> or <literal>imaps</literal> protocol. 11950 Alternatively, a pine-compatible notation is also supported, i.e. 11951 <literal>{[username@]imapserver[:port][/ssl]}path/to/folder</literal> 11952 </para> 11953 <para> 11954 Note that not all servers use <quote>/</quote> as the hierarchy 11955 separator. NeoMutt should correctly notice which separator is being 11956 used by the server and convert paths accordingly. 11957 </para> 11958 <para> 11959 When browsing folders on an IMAP server, you can toggle whether to look 11960 at only the folders you are subscribed to, or all folders with the 11961 <emphasis>toggle-subscribed</emphasis> command. See also the 11962 <link linkend="imap-list-subscribed">$imap_list_subscribed</link> 11963 variable. 11964 </para> 11965 <para> 11966 Polling for new mail on an IMAP server can cause noticeable delays. 11967 So, you'll want to carefully tune the 11968 <link linkend="mail-check">$mail_check</link> and 11969 <link linkend="timeout">$timeout</link> variables. Reasonable values 11970 are: 11971 </para> 11972 11973<screen> 11974set mail_check=90 11975set timeout=15 11976</screen> 11977 11978 <para> 11979 with relatively good results even over slow modem lines. 11980 </para> 11981 <note> 11982 <para> 11983 Note that if you are using mbox as the mail store on UW servers prior 11984 to v12.250, the server has been reported to disconnect a client if 11985 another client selects the same folder. 11986 </para> 11987 </note> 11988 11989 <sect2 id="imap-browser"> 11990 <title>The IMAP Folder Browser</title> 11991 <para> 11992 As of version 1.2, NeoMutt supports browsing mailboxes on an IMAP 11993 server. This is mostly the same as the local file browser, with the 11994 following differences: 11995 </para> 11996 <itemizedlist> 11997 <listitem> 11998 <para> 11999 In lieu of file permissions, NeoMutt displays the string 12000 <quote>IMAP</quote>, possibly followed by the symbol 12001 <quote>+</quote>, indicating that the entry contains both 12002 messages and subfolders. On Cyrus-like servers folders will often 12003 contain both messages and subfolders. A mailbox name with a 12004 trailing delimiter (usually <quote>/</quote> or <quote>.</quote>) 12005 indicates subfolders. 12006 </para> 12007 </listitem> 12008 <listitem> 12009 <para> 12010 For the case where an entry can contain both messages and 12011 subfolders, the selection key (bound to <literal>enter</literal> 12012 by default) will choose to descend into the subfolder view. If 12013 you wish to view the messages in that folder, you must use 12014 <literal>view-file</literal> instead (bound to 12015 <literal>space</literal> by default). 12016 </para> 12017 </listitem> 12018 <listitem> 12019 <para> 12020 You can create, delete and rename mailboxes with the 12021 <literal><create-mailbox></literal>, 12022 <literal><delete-mailbox></literal>, and 12023 <literal><rename-mailbox></literal> commands (default 12024 bindings: <literal>C</literal>, <literal>d</literal> and 12025 <literal>r</literal>, respectively). You may also 12026 <literal><subscribe></literal> and 12027 <literal><unsubscribe></literal> to mailboxes (normally 12028 these are bound to <literal>s</literal> and <literal>u</literal>, 12029 respectively). 12030 </para> 12031 </listitem> 12032 </itemizedlist> 12033 </sect2> 12034 12035 <sect2 id="imap-authentication"> 12036 <title>Authentication</title> 12037 <para> 12038 NeoMutt supports four authentication methods with IMAP servers: SASL, 12039 GSSAPI, CRAM-MD5, and LOGIN. There is also support for the 12040 pseudo-protocol ANONYMOUS, which allows you to log in to a public 12041 IMAP server without having an account. To use ANONYMOUS, simply make 12042 your username blank or <quote>anonymous</quote>. 12043 </para> 12044 <para> 12045 SASL is a special super-authenticator, which selects among several 12046 protocols (including GSSAPI, CRAM-MD5, ANONYMOUS, and DIGEST-MD5) the 12047 most secure method available on your host and the server. Using some 12048 of these methods (including DIGEST-MD5 and possibly GSSAPI), your 12049 entire session will be encrypted and invisible to those teeming 12050 network snoops. It is the best option if you have it. To use it, you 12051 must have the Cyrus SASL library installed on your system and compile 12052 NeoMutt with the <emphasis>--with-sasl</emphasis> flag. 12053 </para> 12054 <para> 12055 NeoMutt will try whichever methods are compiled in and available on 12056 the server, in the following order: SASL, ANONYMOUS, GSSAPI, 12057 CRAM-MD5, LOGIN. 12058 </para> 12059 <para> 12060 There are a few variables which control authentication: 12061 </para> 12062 <itemizedlist> 12063 <listitem> 12064 <para> 12065 <link linkend="imap-user">$imap_user</link> – controls the 12066 username under which you request authentication on the IMAP 12067 server, for all authenticators. This is overridden by an explicit 12068 username in the mailbox path (i.e. by using a mailbox name of the 12069 form <literal>{user@host}</literal>). 12070 </para> 12071 </listitem> 12072 <listitem> 12073 <para> 12074 <link linkend="imap-pass">$imap_pass</link> – a password which 12075 you may preset, used by all authentication methods where 12076 a password is needed. 12077 </para> 12078 </listitem> 12079 <listitem> 12080 <para> 12081 <link linkend="imap-authenticators">$imap_authenticators</link> 12082 – a colon-delimited list of IMAP authentication methods to try, 12083 in the order you wish to try them. If specified, this overrides 12084 NeoMutt's default (attempt everything, in the order listed 12085 above). 12086 </para> 12087 </listitem> 12088 </itemizedlist> 12089 </sect2> 12090 </sect1> 12091 12092 <sect1 id="smtp"> 12093 <title>SMTP Support</title> 12094 <para> 12095 Besides supporting traditional mail delivery through 12096 a sendmail-compatible program, NeoMutt supports delivery through SMTP. 12097 </para> 12098 <para> 12099 If the configuration variable <link linkend="smtp-url">$smtp_url</link> 12100 is set, NeoMutt will contact the given SMTP server to deliver messages; 12101 if it is unset, NeoMutt will use the program specified by 12102 <link linkend="sendmail">$sendmail</link>. 12103 </para> 12104 <para> 12105 For details on the URL syntax, please see 12106 <xref linkend="url-syntax" />. 12107 </para> 12108 <para> 12109 The built-in SMTP support supports encryption (the 12110 <literal>smtps</literal> protocol using SSL or TLS) as well as SMTP 12111 authentication using SASL. The authentication mechanisms for SASL are 12112 specified in 12113 <link linkend="smtp-authenticators">$smtp_authenticators</link> 12114 defaulting to an empty list which makes NeoMutt try all available 12115 methods from most-secure to least-secure. 12116 </para> 12117 </sect1> 12118 12119 <sect1 id="oauth"> 12120 <title>OAUTHBEARER and XOAUTH2 Support</title> 12121 <para> 12122 Preliminary OAUTH support for IMAP, POP, and SMTP is provided via external scripts. 12123 </para> 12124 <para> 12125 At least for Gmail, you can use the <literal>oauth2.py</literal>script 12126 from Google's gmail-oauth2-tools: 12127 <ulink url="https://github.com/google/gmail-oauth2-tools/blob/master/python/oauth2.py">https://github.com/google/gmail-oauth2-tools/blob/master/python/oauth2.py</ulink> 12128 </para> 12129 <para> 12130 You'll need to get your own oauth client credentials for Gmail here: 12131 <ulink url="https://console.developers.google.com/apis/credentials">https://console.developers.google.com/apis/credentials</ulink> 12132 </para> 12133 <para> 12134 Then, you'd use <literal>oauth2.py</literal> with 12135 <literal>--generate_oauth2_token</literal> to get a refresh token, and 12136 configure NeoMutt with: 12137 </para> 12138 12139<screen> 12140set imap_authenticators="oauthbearer" 12141set imap_oauth_refresh_command="/path/to/oauth2.py --quiet --user=[email_address]\ 12142 --client_id=[client_id] --client_secret=[client_secret]\ 12143 --refresh_token=[refresh_token]" 12144</screen> 12145 12146 <para> 12147 For Office365, you can use the <literal>mutt_oauth2.py</literal> script 12148 written by Alexander Perlis: 12149 <ulink url="https://github.com/neomutt/neomutt/blob/master/contrib/oauth2/mutt_oauth2.py">https://github.com/neomutt/neomutt/blob/master/contrib/oauth2/mutt_oauth2.py</ulink> 12150 </para> 12151 <para> 12152 You'll need to get your own oauth client credentials by following the 12153 script instructions: 12154 <ulink url="https://github.com/neomutt/neomutt/blob/master/contrib/oauth2/mutt_oauth2.py.README">https://github.com/neomutt/neomutt/blob/master/contrib/oauth2/mutt_oauth2.py.README</ulink> 12155 </para> 12156 12157<screen> 12158set imap_authenticators="xoauth2" 12159set imap_oauth_refresh_command="/path/to/mutt_oauth2.py /path/to/token" 12160</screen> 12161 12162 <para> 12163 Substitute pop or smtp for imap in the above examples to configure for 12164 those. Please note that xoauth2 support has not yet been implemented for 12165 pop. 12166 </para> 12167 </sect1> 12168 12169 <sect1 id="account-hook"> 12170 <title>Managing Multiple Accounts</title> 12171 <para> 12172 Usage: 12173 </para> 12174 <cmdsynopsis> 12175 <command>account-hook</command> 12176 <arg choice="plain"> 12177 <replaceable class="parameter">regex</replaceable> 12178 </arg> 12179 <arg choice="plain"> 12180 <replaceable class="parameter">command</replaceable> 12181 </arg> 12182 </cmdsynopsis> 12183 <para> 12184 If you happen to have accounts on multiple IMAP, POP and/or SMTP 12185 servers, you may find managing all the authentication settings 12186 inconvenient and error-prone. The 12187 <link linkend="account-hook"><command>account-hook</command></link> 12188 command may help. This hook works like 12189 <link linkend="folder-hook"><command>folder-hook</command></link> but 12190 is invoked whenever NeoMutt needs to access a remote mailbox (including 12191 inside the folder browser), not just when you open the mailbox. This 12192 includes (for example) polling for new mail, storing Fcc messages and 12193 saving messages to a folder. As a consequence, 12194 <link linkend="account-hook"><command>account-hook</command></link> 12195 should only be used to set connection-related settings such as 12196 passwords or tunnel commands but not settings such as sender address or 12197 name (because in general it should be considered unpredictable which 12198 <link linkend="account-hook"><command>account-hook</command></link> was 12199 last used). 12200 </para> 12201 <para> 12202 Some examples: 12203 </para> 12204 12205<screen> 12206account-hook . 'unset imap_user; unset imap_pass; unset tunnel' 12207account-hook imap://host1/ 'set imap_user=me1 imap_pass=foo' 12208account-hook imap://host2/ 'set tunnel="ssh host2 /usr/libexec/imapd"' 12209account-hook smtp://user@host3/ 'set tunnel="ssh host3 /usr/libexec/smtpd"' 12210</screen> 12211 12212 <para> 12213 To manage multiple accounts with, for example, different values of 12214 <link linkend="record">$record</link> or sender addresses, 12215 <link linkend="folder-hook"><command>folder-hook</command></link> has 12216 to be be used together with the 12217 <link linkend="mailboxes"><command>mailboxes</command></link> command. 12218 </para> 12219 <example id="ex-multiaccount"> 12220 <title>Managing multiple accounts</title> 12221 12222<screen> 12223mailboxes imap://user@host1/INBOX 12224folder-hook imap://user@host1/ 'set folder=imap://host1/ ; set record=+INBOX/Sent' 12225mailboxes imap://user@host2/INBOX 12226folder-hook imap://user@host2/ 'set folder=imap://host2/ ; set record=+INBOX/Sent' 12227</screen> 12228 12229 </example> 12230 <para> 12231 In example 12232 <xref linkend="ex-multiaccount" /> the folders are defined using 12233 <link linkend="mailboxes"><command>mailboxes</command></link> so 12234 NeoMutt polls them for new mail. Each 12235 <link linkend="folder-hook"><command>folder-hook</command></link> 12236 triggers when one mailbox below each IMAP account is opened and sets 12237 <link linkend="folder">$folder</link> to the account's root folder. 12238 Next, it sets 12239 <link linkend="record">$record</link> to the 12240 <emphasis>INBOX/Sent</emphasis> folder below the newly set 12241 <link linkend="folder">$folder</link>. Please notice that the value the 12242 <quote>+</quote> <link linkend="shortcuts">mailbox shortcut</link> 12243 refers to depends on the <emphasis>current</emphasis> value of 12244 <link linkend="folder">$folder</link> and therefore has to be set 12245 separately per account. Setting other values like 12246 <link linkend="from">$from</link> or 12247 <link linkend="signature">$signature</link> is analogous to setting 12248 <link linkend="record">$record</link>. 12249 </para> 12250 </sect1> 12251 12252 <sect1 id="caching"> 12253 <title>Local Caching</title> 12254 <para> 12255 NeoMutt contains two types of local caching: <emphasis>(1)</emphasis> 12256 the so-called <quote>header caching</quote> and 12257 <emphasis>(2)</emphasis> the so-called <quote>body caching</quote> 12258 which are both described in this section. 12259 </para> 12260 <para> 12261 Header caching is optional as it depends on external libraries, body 12262 caching is always enabled if NeoMutt is compiled with POP and/or IMAP 12263 support as these use it (body caching requires no external library). 12264 </para> 12265 12266 <sect2 id="header-caching"> 12267 <title>Header Caching</title> 12268 <para> 12269 NeoMutt provides optional support for caching message headers for the 12270 following types of folders: IMAP, POP, Maildir and MH. Header caching 12271 greatly speeds up opening large folders because for remote folders, 12272 headers usually only need to be downloaded once. For Maildir and MH, 12273 reading the headers from a single file is much faster than looking at 12274 possibly thousands of single files (since Maildir and MH use one file 12275 per message.) 12276 </para> 12277 <para> 12278 Header caching can be enabled by configuring one of the database 12279 backends. One of bdb, gdbm, kyotocabinet, lmdb, qdbm, rocksdb, tdb, 12280 tokyocabinet. 12281 </para> 12282 <para> 12283 If enabled, <link linkend="header-cache">$header_cache</link> can be 12284 used to either point to a file or a directory. If set to point to 12285 a file, one database file for all folders will be used (which may 12286 result in lower performance), but one file per folder if it points to 12287 a directory. 12288 </para> 12289 <para> 12290 Additionally, 12291 <link linkend="header-cache-backend">$header_cache_backend</link> must 12292 be set to specify which backend to use. The list of available 12293 backends can be specified at configure time with a set of 12294 --with-<backend> options. Currently, the following backends are 12295 supported: bdb, gdbm, kyotocabinet, lmdb, qdbm, rocksdb, tdb, 12296 tokyocabinet. 12297 </para> 12298 <para> 12299 Take a look at the benchmark script provided in the following directory: 12300 <ulink url="https://github.com/neomutt/neomutt/blob/master/contrib/hcache-bench">contrib/hcache-bench</ulink> 12301 of the neomutt sources, there you can find a way of finding the 12302 storage backend for your needs. 12303 </para> 12304 </sect2> 12305 12306 <sect2 id="body-caching"> 12307 <title>Body Caching</title> 12308 <para> 12309 Both cache methods can be combined using the same directory for 12310 storage (and for IMAP/POP even provide meaningful file names) which 12311 simplifies manual maintenance tasks. 12312 </para> 12313 <para> 12314 In addition to caching message headers only, NeoMutt can also cache 12315 whole message bodies. This results in faster display of messages for 12316 POP and IMAP folders because messages usually have to be downloaded 12317 only once. 12318 </para> 12319 <para> 12320 For configuration, the variable 12321 <link linkend="message-cachedir">$message_cachedir</link> must point 12322 to a directory. There, NeoMutt will create a hierarchy of 12323 subdirectories named like the account and mailbox path the cache is 12324 for. 12325 </para> 12326 </sect2> 12327 12328 <sect2 id="cache-dirs"> 12329 <title>Cache Directories</title> 12330 <para> 12331 For using both, header and body caching, 12332 <link linkend="header-cache">$header_cache</link> and 12333 <link linkend="message-cachedir">$message_cachedir</link> can be 12334 safely set to the same value. 12335 </para> 12336 <para> 12337 In a header or body cache directory, NeoMutt creates a directory 12338 hierarchy named like: <literal>proto:user@hostname</literal> where 12339 <literal>proto</literal> is either <quote>pop</quote> or 12340 <quote>imap.</quote> Within there, for each folder, NeoMutt stores 12341 messages in single files and header caches in files with the 12342 <quote>.hcache</quote> extension. All files can be removed as needed 12343 if the consumed disk space becomes an issue as NeoMutt will silently 12344 fetch missing items again. Pathnames are always stored in UTF-8 12345 encoding. 12346 </para> 12347 <para> 12348 For Maildir and MH, the header cache files are named after the MD5 12349 checksum of the path. 12350 </para> 12351 </sect2> 12352 12353 <sect2 id="maint-cache"> 12354 <title>Maintenance</title> 12355 <para> 12356 NeoMutt does not (yet) support maintenance features for header cache 12357 database files so that files have to be removed in case they grow too 12358 big. It depends on the database library used for header caching 12359 whether disk space freed by removing messages is re-used. 12360 </para> 12361 <para> 12362 For body caches, NeoMutt can keep the local cache in sync with the 12363 remote mailbox if the 12364 <link linkend="message-cache-clean">$message_cache_clean</link> 12365 variable is set. Cleaning means to remove messages from the cache 12366 which are no longer present in the mailbox which only happens when 12367 other mail clients or instances of NeoMutt using a different body 12368 cache location delete messages (NeoMutt itself removes deleted 12369 messages from the cache when syncing a mailbox). As cleaning can take 12370 a noticeable amount of time, it should not be set in general but only 12371 occasionally. 12372 </para> 12373 </sect2> 12374 </sect1> 12375 12376 <sect1 id="sending-mixmaster"> 12377 <title>Sending Anonymous Messages via Mixmaster</title> 12378 <para> 12379 You may also have compiled NeoMutt to co-operate with Mixmaster, an 12380 anonymous remailer. Mixmaster permits you to send your messages 12381 anonymously using a chain of remailers. Mixmaster support in NeoMutt is 12382 for mixmaster version 2.04 or later. 12383 </para> 12384 <para> 12385 To use it, you'll have to obey certain restrictions. Most important, 12386 you cannot use the <literal>Cc</literal> and <literal>Bcc</literal> 12387 headers. To tell NeoMutt to use mixmaster, you have to select 12388 a remailer chain, using the mix function on the compose menu. 12389 </para> 12390 <para> 12391 The chain selection screen is divided into two parts. In the (larger) 12392 upper part, you get a list of remailers you may use. In the lower part, 12393 you see the currently selected chain of remailers. 12394 </para> 12395 <para> 12396 You can navigate in the chain using the 12397 <literal><chain-prev></literal> and 12398 <literal><chain-next></literal> functions, which are by default 12399 bound to the left and right arrows and to the <literal>h</literal> and 12400 <literal>l</literal> keys (think vi keyboard bindings). To insert 12401 a remailer at the current chain position, use the 12402 <literal><insert></literal> function. To append a remailer behind 12403 the current chain position, use <literal><select-entry></literal> 12404 or <literal><append></literal>. You can also delete entries from 12405 the chain, using the corresponding function. Finally, to abandon your 12406 changes, leave the menu, or <literal><accept></literal> them 12407 pressing (by default) the <literal>Return</literal> key. 12408 </para> 12409 <para> 12410 Note that different remailers do have different capabilities, indicated 12411 in the %c entry of the remailer menu lines (see 12412 <link linkend="mix-entry-format">$mix_entry_format</link>). Most 12413 important is the <quote>middleman</quote> capability, indicated by 12414 a capital <quote>M</quote>: This means that the remailer in question 12415 cannot be used as the final element of a chain, but will only forward 12416 messages to other mixmaster remailers. For details on the other 12417 capabilities, please have a look at the mixmaster documentation. 12418 </para> 12419 </sect1> 12420 12421 <sect1 id="attach-headers-color"> 12422 <title>Attach Headers Color Feature</title> 12423 <subtitle>Color attachment headers using regex, just like mail 12424 bodies</subtitle> 12425 12426 <sect2 id="attach-headers-color-support"> 12427 <title>Support</title> 12428 <para> 12429 <emphasis role="bold">Since:</emphasis> NeoMutt 2016-09-10 12430 </para> 12431 <para> 12432 <emphasis role="bold">Dependencies:</emphasis> None 12433 </para> 12434 </sect2> 12435 12436 <sect2 id="attach-headers-color-intro"> 12437 <title>Introduction</title> 12438 <para> 12439 This feature allows specifying regexes to color attachment headers 12440 just like the mail body would. The headers are the parts colored by 12441 the <literal>attachment</literal> color. Coloring them is useful to 12442 highlight the results of GPGME's signature checks or simply the 12443 mimetype or size of the attachment. Only the part matched by the 12444 regex is colored. 12445 </para> 12446 </sect2> 12447 12448 <sect2 id="attach-headers-color-usage"> 12449 <title>Usage</title> 12450 <para> 12451 The <literal>attach_headers</literal> color should be used just like 12452 the <literal>body</literal> color. 12453 </para> 12454 <screen>color attach_headers foreground background pattern</screen> 12455 </sect2> 12456 12457 <sect2 id="attach-headers-color-neomuttrc"> 12458 <title>neomuttrc</title> 12459 12460<screen> 12461<emphasis role="comment"># Example NeoMutt config file for the attach-headers-color feature.</emphasis> 12462 12463<emphasis role="comment"># Color if the attachment is autoviewed</emphasis> 12464color attach_headers brightgreen default "Autoview" 12465<emphasis role="comment"># Color only the brackets around the headers</emphasis> 12466color attach_headers brightyellow default "^\\[--" 12467color attach_headers brightyellow default "--]$" 12468<emphasis role="comment"># Color the mime type and the size</emphasis> 12469color attach_headers green default "Type: [a-z]+/[a-z0-9\-]+" 12470color attach_headers green default "Size: [0-9\.]+[KM]" 12471<emphasis role="comment"># Color GPGME signature checks</emphasis> 12472color attach_headers brightgreen default "Good signature from.*" 12473color attach_headers brightred default "Bad signature from.*" 12474color attach_headers brightred default "BAD signature from.*" 12475color attach_headers brightred default "Note: This key has expired!" 12476color attach_headers brightmagenta default "Problem signature from.*" 12477color attach_headers brightmagenta default "WARNING: This key is not certified with a trusted signature!" 12478color attach_headers brightmagenta default " There is no indication that the signature belongs to the owner." 12479color attach_headers brightmagenta default "can't handle these multiple signatures" 12480color attach_headers brightmagenta default "signature verification suppressed" 12481color attach_headers brightmagenta default "invalid node with packet of type" 12482 12483<emphasis role="comment"># vim: syntax=neomuttrc</emphasis> 12484</screen> 12485 12486 </sect2> 12487 12488 <sect2 id="attach-headers-color-see-also"> 12489 <title>See Also</title> 12490 <itemizedlist> 12491 <listitem> 12492 <para> 12493 <link linkend="color">Color command</link> 12494 </para> 12495 </listitem> 12496 <listitem> 12497 <para> 12498 <link linkend="regex">Regular Expressions</link> 12499 </para> 12500 </listitem> 12501 </itemizedlist> 12502 </sect2> 12503 12504 <sect2 id="attach-headers-color-known-bugs"> 12505 <title>Known Bugs</title> 12506 <para> 12507 None 12508 </para> 12509 </sect2> 12510 12511 <sect2 id="attach-headers-color-credits"> 12512 <title>Credits</title> 12513 <para> 12514 Guillaume Brogi 12515 </para> 12516 </sect2> 12517 </sect1> 12518 12519 <sect1 id="compose-to-sender"> 12520 <title>Compose to Sender Feature</title> 12521 <subtitle>Send new mail to the sender of the current mail</subtitle> 12522 12523 <sect2 id="compose-to-sender-support"> 12524 <title>Support</title> 12525 <para> 12526 <emphasis role="bold">Since:</emphasis> NeoMutt 2016-10-02 12527 </para> 12528 <para> 12529 <emphasis role="bold">Dependencies:</emphasis> None 12530 </para> 12531 </sect2> 12532 12533 <sect2 id="compose-to-sender-intro"> 12534 <title>Introduction</title> 12535 <para> 12536 The compose-to-sender feature adds a new command to start composing 12537 a new email to the sender of the current message. This is not 12538 a reply, but a new, separate, message. 12539 </para> 12540 <para> 12541 It works on tagged messages too, sending one email to all of the 12542 senders of the tagged messages. 12543 </para> 12544 </sect2> 12545 12546 <sect2 id="compose-to-sender-functions"> 12547 <title>Functions</title> 12548 <para> 12549 compose-to-sender adds the following function to NeoMutt. By default, 12550 it is not bound to a key. 12551 </para> 12552 12553 <table id="table-compose-to-sender-functions"> 12554 <title>compose-to-sender Functions</title> 12555 <tgroup cols="3"> 12556 <thead> 12557 <row> 12558 <entry>Menus</entry> 12559 <entry>Function</entry> 12560 <entry>Description</entry> 12561 </row> 12562 </thead> 12563 <tbody> 12564 <row> 12565 <entry>index,pager</entry> 12566 <entry><literal><compose-to-sender></literal></entry> 12567 <entry>compose a new email to the sender of the current email</entry> 12568 </row> 12569 </tbody> 12570 </tgroup> 12571 </table> 12572 </sect2> 12573 12574 <sect2 id="compose-to-sender-neomuttrc"> 12575 <title>neomuttrc</title> 12576 12577<screen> 12578<emphasis role="comment"># Example NeoMutt config file for the compose-to-sender feature.</emphasis> 12579 12580<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 12581<emphasis role="comment"># FUNCTIONS – shown with an example mapping</emphasis> 12582<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 12583<emphasis role="comment"># Compose a new email (not a reply) to the sender</emphasis> 12584bind index,pager @ compose-to-sender 12585 12586<emphasis role="comment"># vim: syntax=neomuttrc</emphasis> 12587</screen> 12588 12589 </sect2> 12590 12591 <sect2 id="compose-to-sender-known-bugs"> 12592 <title>Known Bugs</title> 12593 <para> 12594 None 12595 </para> 12596 </sect2> 12597 12598 <sect2 id="compose-to-sender-credits"> 12599 <title>Credits</title> 12600 <para> 12601 Brian Medley, Guillaume Brogi 12602 </para> 12603 </sect2> 12604 </sect1> 12605 12606 <sect1 id="compress"> 12607 <title>Compressed Folders Feature</title> 12608 <subtitle>Read from/write to compressed mailboxes</subtitle> 12609 12610 <sect2 id="compress-support"> 12611 <title>Support</title> 12612 <para> 12613 <emphasis role="bold">Since:</emphasis> NeoMutt 2016-05-30 12614 </para> 12615 <para> 12616 <emphasis role="bold">Dependencies:</emphasis> None 12617 </para> 12618 </sect2> 12619 12620 <sect2 id="compress-intro"> 12621 <title>Introduction</title> 12622 <para> 12623 The Compressed Folder feature allows NeoMutt to read mailbox files 12624 that are compressed. But it isn't limited to compressed files. It 12625 works well with encrypted files, too. In fact, if you can create 12626 a program/script to convert to and from your format, then NeoMutt can 12627 read it. 12628 </para> 12629 <para> 12630 The feature adds three hooks to NeoMutt: 12631 <literal>open-hook</literal>, <literal>close-hook</literal> and 12632 <literal>append-hook</literal>. They define commands to: uncompress 12633 a file; compress a file; append messages to an already compressed 12634 file. 12635 </para> 12636 <para> 12637 There are some examples of both compressed and encrypted files, 12638 later. For now, the documentation will just concentrate on compressed 12639 files. 12640 </para> 12641 </sect2> 12642 12643 <sect2 id="compress-commands"> 12644 <title>Commands</title> 12645 <cmdsynopsis> 12646 <command>open-hook</command> 12647 <arg choice="plain"> 12648 <replaceable class="parameter">regex</replaceable> 12649 </arg> 12650 <arg choice="plain"> 12651 <replaceable class="parameter">"shell-command"</replaceable> 12652 </arg> 12653 <command>close-hook</command> 12654 <arg choice="plain"> 12655 <replaceable class="parameter">regex</replaceable> 12656 </arg> 12657 <arg choice="plain"> 12658 <replaceable class="parameter">"shell-command"</replaceable> 12659 </arg> 12660 <command>append-hook</command> 12661 <arg choice="plain"> 12662 <replaceable class="parameter">regex</replaceable> 12663 </arg> 12664 <arg choice="plain"> 12665 <replaceable class="parameter">"shell-command"</replaceable> 12666 </arg> 12667 </cmdsynopsis> 12668 <para> 12669 The shell-command must contain two placeholders for filenames: 12670 <literal>%f</literal> and <literal>%t</literal>. These represent 12671 <quote>from</quote> and <quote>to</quote> filenames. These 12672 placeholders should be placed inside single-quotes to prevent 12673 unintended shell expansions. 12674 </para> 12675 <para> 12676 If you need the exact string <quote>%f</quote> or <quote>%t</quote> 12677 in your command, simply double up the <quote>%</quote> character, 12678 e.g. <quote>%%f</quote> or <quote>%%t</quote>. 12679 </para> 12680 12681 <table id="table-compress-optional"> 12682 <title>Not all Hooks are Required</title> 12683 <tgroup cols="5"> 12684 <thead> 12685 <row> 12686 <entry>Open</entry> 12687 <entry>Close</entry> 12688 <entry>Append</entry> 12689 <entry>Effect</entry> 12690 <entry>Useful if</entry> 12691 </row> 12692 </thead> 12693 <tbody> 12694 <row> 12695 <entry>Open</entry> 12696 <entry>—</entry> 12697 <entry>—</entry> 12698 <entry> 12699 Folder is readonly 12700 </entry> 12701 <entry>The folder is just a backup</entry> 12702 </row> 12703 <row> 12704 <entry>Open</entry> 12705 <entry>Close</entry> 12706 <entry>—</entry> 12707 <entry> 12708 Folder is read/write, but the entire folder must be written 12709 if anything is changed 12710 </entry> 12711 <entry>Your compression format doesn't support appending</entry> 12712 </row> 12713 <row> 12714 <entry>Open</entry> 12715 <entry>Close</entry> 12716 <entry>Append</entry> 12717 <entry> 12718 Folder is read/write and emails can be efficiently added to 12719 the end 12720 </entry> 12721 <entry>Your compression format supports appending</entry> 12722 </row> 12723 <row> 12724 <entry>Open</entry> 12725 <entry>—</entry> 12726 <entry>Append</entry> 12727 <entry> 12728 Folder is readonly, but can be appended to 12729 </entry> 12730 <entry>You want to store emails, but never change them</entry> 12731 </row> 12732 </tbody> 12733 </tgroup> 12734 </table> 12735 <note> 12736 <para> 12737 The command: 12738 </para> 12739 <itemizedlist> 12740 <listitem> 12741 <para> 12742 should return a non-zero exit status on failure 12743 </para> 12744 </listitem> 12745 <listitem> 12746 <para> 12747 should not delete any files 12748 </para> 12749 </listitem> 12750 </itemizedlist> 12751 </note> 12752 12753 <sect3 id="open-hook"> 12754 <title>Read from compressed mailbox</title> 12755 <screen>open-hook regex "shell-command"</screen> 12756 <para> 12757 If NeoMutt is unable to open a file, it then looks for 12758 <literal>open-hook</literal> that matches the filename. 12759 </para> 12760 <para> 12761 If your compression program doesn't have a well-defined extension, 12762 then you can use <literal>.</literal> as the regex. 12763 </para> 12764 12765 <example id="compress-open-hook-example"> 12766 <title>Example of 12767 <literal>open-hook</literal></title> 12768 12769<screen> 12770open-hook '\.gz$' "gzip --stdout --decompress '%f' > '%t'" 12771</screen> 12772 12773 <itemizedlist> 12774 <listitem> 12775 <para> 12776 NeoMutt finds a file, <quote>example.gz</quote>, that it 12777 can't read 12778 </para> 12779 </listitem> 12780 <listitem> 12781 <para> 12782 NeoMutt has an <literal>open-hook</literal> whose regex 12783 matches the filename: <literal>\.gz$</literal> 12784 </para> 12785 </listitem> 12786 <listitem> 12787 <para> 12788 NeoMutt uses the command <literal>gzip -cd</literal> to 12789 create a temporary file that it <emphasis>can</emphasis> read 12790 </para> 12791 </listitem> 12792 </itemizedlist> 12793 </example> 12794 </sect3> 12795 12796 <sect3 id="close-hook"> 12797 <title>Write to a compressed mailbox</title> 12798 <screen>close-hook regex "shell-command"</screen> 12799 <para> 12800 When NeoMutt has finished with a compressed mail folder, it will 12801 look for a matching <literal>close-hook</literal> to recompress the 12802 file. This hook is 12803 <link linkend="table-compress-optional">optional</link>. 12804 </para> 12805 <note> 12806 <para> 12807 If the folder has not been modified, the 12808 <literal>close-hook</literal> will not be called. 12809 </para> 12810 </note> 12811 12812 <example id="compress-close-hook-example"> 12813 <title>Example of 12814 <literal>close-hook</literal></title> 12815 <screen>close-hook '\.gz$' "gzip --stdout '%t' > '%f'"</screen> 12816 <itemizedlist> 12817 <listitem> 12818 <para> 12819 NeoMutt has finished with a folder, 12820 <quote>example.gz</quote>, that it opened with 12821 <literal>open-hook</literal> 12822 </para> 12823 </listitem> 12824 <listitem> 12825 <para> 12826 The folder has been modified 12827 </para> 12828 </listitem> 12829 <listitem> 12830 <para> 12831 NeoMutt has a <literal>close-hook</literal> whose regex 12832 matches the filename: <literal>\.gz$</literal> 12833 </para> 12834 </listitem> 12835 <listitem> 12836 <para> 12837 NeoMutt uses the command <literal>gzip -c</literal> to create 12838 a new compressed file 12839 </para> 12840 </listitem> 12841 </itemizedlist> 12842 </example> 12843 <note> 12844 <para> 12845 The <literal>close-hook</literal> can also include extra 12846 options, e.g. compression level: <literal>--best</literal> 12847 </para> 12848 </note> 12849 </sect3> 12850 12851 <sect3 id="append-hook"> 12852 <title>Append to a compressed mailbox</title> 12853 <screen>append-hook regex "shell-command"</screen> 12854 <para> 12855 When NeoMutt wants to append an email to a compressed mail folder, 12856 it will look for a matching <literal>append-hook</literal>. This 12857 hook is <link linkend="table-compress-optional">optional</link>. 12858 </para> 12859 <para> 12860 Using the <literal>append-hook</literal> will save time, but 12861 NeoMutt won't be able to determine the type of the mail folder 12862 inside the compressed file. 12863 </para> 12864 <para> 12865 NeoMutt will <emphasis>assume</emphasis> the type to be that of the 12866 <literal>$mbox_type</literal> variable. NeoMutt also uses this type 12867 for temporary files. 12868 </para> 12869 <para> 12870 NeoMutt will only use the <literal>append-hook</literal> for 12871 existing files. The <literal>close-hook</literal> will be used for 12872 empty, or missing files. 12873 </para> 12874 <note> 12875 <para> 12876 If your command writes to stdout, it is vital that you use 12877 <literal>>></literal> in the <quote>append-hook</quote>. If 12878 not, data will be lost. 12879 </para> 12880 </note> 12881 12882 <example id="compress-append-hook-example"> 12883 <title>Example of 12884 <literal>append-hook</literal></title> 12885 12886<screen> 12887append-hook '\.gz$' "gzip --stdout '%t' >> '%f'" 12888</screen> 12889 12890 <itemizedlist> 12891 <listitem> 12892 <para> 12893 NeoMutt wants to append an email to a folder, 12894 <quote>example.gz</quote>, that it opened with 12895 <literal>open-hook</literal> 12896 </para> 12897 </listitem> 12898 <listitem> 12899 <para> 12900 NeoMutt has an <literal>append-hook</literal> whose regex 12901 matches the filename: <literal>\.gz$</literal> 12902 </para> 12903 </listitem> 12904 <listitem> 12905 <para> 12906 NeoMutt knows the mailbox type from the 12907 <literal>$mbox</literal> variable 12908 </para> 12909 </listitem> 12910 <listitem> 12911 <para> 12912 NeoMutt uses the command <literal>gzip -c</literal> to append 12913 to an existing compressed file 12914 </para> 12915 </listitem> 12916 </itemizedlist> 12917 </example> 12918 <note> 12919 <para> 12920 The <literal>append-hook</literal> can also include extra 12921 options, e.g. compression level: <literal>--best</literal> 12922 </para> 12923 </note> 12924 </sect3> 12925 12926 <sect3 id="compress-empty"> 12927 <title>Empty Files</title> 12928 <para> 12929 NeoMutt assumes that an empty file is not compressed. In this 12930 situation, unset <link linkend="save-empty">$save_empty</link>, so 12931 that the compressed file will be removed if you delete all of the 12932 messages. 12933 </para> 12934 </sect3> 12935 12936 <sect3 id="compress-security"> 12937 <title>Security</title> 12938 <para> 12939 Encrypted files are decrypted into temporary files which are stored 12940 in the <link linkend="tmpdir">$tmpdir</link> directory. This could 12941 be a security risk. 12942 </para> 12943 </sect3> 12944 </sect2> 12945 12946 <sect2 id="compress-neomuttrc"> 12947 <title>neomuttrc</title> 12948 12949<screen> 12950<emphasis role="comment"># Example NeoMutt config file for the compress feature.</emphasis> 12951 12952<emphasis role="comment"># This feature adds three hooks to NeoMutt which allow it to</emphasis> 12953<emphasis role="comment"># work with compressed, or encrypted, mailboxes.</emphasis> 12954 12955<emphasis role="comment"># The hooks are of the form:</emphasis> 12956<emphasis role="comment"># open-hook regex "shell-command"</emphasis> 12957<emphasis role="comment"># close-hook regex "shell-command"</emphasis> 12958<emphasis role="comment"># append-hook regex "shell-command"</emphasis> 12959<emphasis role="comment"># The 'append-hook' is optional.</emphasis> 12960 12961<emphasis role="comment"># Handler for gzip compressed mailboxes</emphasis> 12962open-hook '\.gz$' "gzip --stdout --decompress '%f' > '%t'" 12963close-hook '\.gz$' "gzip --stdout '%t' > '%f'" 12964append-hook '\.gz$' "gzip --stdout '%t' >> '%f'" 12965<emphasis role="comment"># Handler for bzip2 compressed mailboxes</emphasis> 12966open-hook '\.bz2$' "bzip2 --stdout --decompress '%f' > '%t'" 12967close-hook '\.bz2$' "bzip2 --stdout '%t' > '%f'" 12968append-hook '\.bz2$' "bzip2 --stdout '%t' >> '%f'" 12969<emphasis role="comment"># Handler for xz compressed mailboxes</emphasis> 12970open-hook '\.xz$' "xz --stdout --decompress '%f' > '%t'" 12971close-hook '\.xz$' "xz --stdout '%t' > '%f'" 12972append-hook '\.xz$' "xz --stdout '%t' >> '%f'" 12973<emphasis role="comment"># Handler for pgp encrypted mailboxes</emphasis> 12974<emphasis role="comment"># PGP does not support appending to an encrypted file</emphasis> 12975open-hook '\.pgp$' "pgp -f < '%f' > '%t'" 12976close-hook '\.pgp$' "pgp -fe YourPgpUserIdOrKeyId < '%t' > '%f'" 12977<emphasis role="comment"># Handler for gpg encrypted mailboxes</emphasis> 12978<emphasis role="comment"># gpg does not support appending to an encrypted file</emphasis> 12979open-hook '\.gpg$' "gpg --decrypt < '%f' > '%t'" 12980close-hook '\.gpg$' "gpg --encrypt --recipient YourGpgUserIdOrKeyId < '%t' > '%f'" 12981 12982<emphasis role="comment"># vim: syntax=neomuttrc</emphasis> 12983</screen> 12984 12985 </sect2> 12986 12987 <sect2 id="compress-see-also"> 12988 <title>See Also</title> 12989 <itemizedlist> 12990 <listitem> 12991 <para> 12992 <link linkend="regex">Regular Expressions</link> 12993 </para> 12994 </listitem> 12995 <listitem> 12996 <para> 12997 <link linkend="tmpdir">$tmpdir</link> 12998 </para> 12999 </listitem> 13000 <listitem> 13001 <para> 13002 <link linkend="mbox-type">$mbox_type</link> 13003 </para> 13004 </listitem> 13005 <listitem> 13006 <para> 13007 <link linkend="save-empty">$save_empty</link> 13008 </para> 13009 </listitem> 13010 <listitem> 13011 <para> 13012 <link linkend="folder-hook">folder-hook</link> 13013 </para> 13014 </listitem> 13015 </itemizedlist> 13016 </sect2> 13017 13018 <sect2 id="compress-credits"> 13019 <title>Credits</title> 13020 <para> 13021 Roland Rosenfeld, Alain Penders, Christoph <quote>Myon</quote> Berg, 13022 Evgeni Golov, Richard Russon 13023 </para> 13024 </sect2> 13025 </sect1> 13026 13027 <sect1 id="cond-date"> 13028 <title>Conditional Dates Feature</title> 13029 <subtitle>Use rules to choose date format</subtitle> 13030 13031 <sect2 id="cond-date-support"> 13032 <title>Support</title> 13033 <para> 13034 <emphasis role="bold">Since:</emphasis> NeoMutt 2016-03-07 13035 </para> 13036 <variablelist> 13037 <varlistentry> 13038 <term> 13039 <emphasis role="bold">Dependencies:</emphasis> 13040 </term> 13041 <listitem> 13042 <para> 13043 <link linkend="nested-if">nested-if feature</link> 13044 </para> 13045 </listitem> 13046 </varlistentry> 13047 </variablelist> 13048 </sect2> 13049 13050 <sect2 id="cond-date-intro"> 13051 <title>Introduction</title> 13052 <para> 13053 The <quote>Conditional Dates</quote> feature allows you to construct 13054 <link linkend="index-format">$index_format</link> expressions based 13055 on the age of the email. 13056 </para> 13057 <para> 13058 NeoMutt's default <literal>$index_format</literal> displays email 13059 dates in the form: abbreviated-month day-of-month – 13060 <quote>Jan 14</quote>. 13061 </para> 13062 <para> 13063 The format is configurable but only per-mailbox. This feature allows 13064 you to configure the display depending on the age of the email. 13065 </para> 13066 13067 <table id="table-cond-date-scheme"> 13068 <title>Potential Formatting Scheme</title> 13069 <tgroup cols="3"> 13070 <thead> 13071 <row> 13072 <entry>Email Sent</entry> 13073 <entry>Format</entry> 13074 <entry>Example</entry> 13075 </row> 13076 </thead> 13077 <tbody> 13078 <row> 13079 <entry>Today</entry> 13080 <entry><literal>%H:%M</literal></entry> 13081 <entry>13:23</entry> 13082 </row> 13083 <row> 13084 <entry>This Month</entry> 13085 <entry><literal>%a %d</literal></entry> 13086 <entry>Thu 17</entry> 13087 </row> 13088 <row> 13089 <entry>This Year</entry> 13090 <entry><literal>%b %d</literal></entry> 13091 <entry>Dec 10</entry> 13092 </row> 13093 <row> 13094 <entry>Older than 1 Year</entry> 13095 <entry><literal>%m/%y</literal></entry> 13096 <entry>06/14</entry> 13097 </row> 13098 </tbody> 13099 </tgroup> 13100 </table> 13101 <para> 13102 For an explanation of the date formatting strings, see 13103 <literal>strftime(3).</literal> 13104 </para> 13105 <para> 13106 By carefully picking your formats, the dates can remain unambiguous 13107 and compact. 13108 </para> 13109 <para> 13110 NeoMutt's conditional format strings have the form: (whitespace 13111 introduced for clarity) 13112 </para> 13113 <screen>%? TEST ? TRUE & FALSE ?</screen> 13114 <para> 13115 The examples below use the test <quote>%[</quote> – the date of the 13116 message in the local timezone. They will also work with 13117 <quote>%(</quote> – the local time that the message arrived. 13118 </para> 13119 <para> 13120 The date tests are of the form: 13121 </para> 13122 <screen>%[nX? TRUE & FALSE ?</screen> 13123 <itemizedlist> 13124 <listitem> 13125 <para> 13126 <quote>n</quote> is an optional count (defaults to 1 if missing) 13127 </para> 13128 </listitem> 13129 <listitem> 13130 <para> 13131 <quote>X</quote> is the time period 13132 </para> 13133 </listitem> 13134 </itemizedlist> 13135 13136 <table id="table-cond-date-format-codes"> 13137 <title>Date Formatting Codes</title> 13138 <tgroup cols="2"> 13139 <thead> 13140 <row> 13141 <entry>Letter</entry> 13142 <entry>Time Period</entry> 13143 </row> 13144 </thead> 13145 <tbody> 13146 <row> 13147 <entry>y</entry> 13148 <entry>Years</entry> 13149 </row> 13150 <row> 13151 <entry>m</entry> 13152 <entry>Months</entry> 13153 </row> 13154 <row> 13155 <entry>w</entry> 13156 <entry>Weeks</entry> 13157 </row> 13158 <row> 13159 <entry>d</entry> 13160 <entry>Days</entry> 13161 </row> 13162 <row> 13163 <entry>H</entry> 13164 <entry>Hours</entry> 13165 </row> 13166 <row> 13167 <entry>M</entry> 13168 <entry>Minutes</entry> 13169 </row> 13170 </tbody> 13171 </tgroup> 13172 </table> 13173 13174 <table id="table-cond-date-example-tests"> 13175 <title>Example Date Tests</title> 13176 <tgroup cols="2"> 13177 <thead> 13178 <row> 13179 <entry>Test</entry> 13180 <entry>Meaning</entry> 13181 </row> 13182 </thead> 13183 <tbody> 13184 <row> 13185 <entry><literal>%[y</literal></entry> 13186 <entry>This year</entry> 13187 </row> 13188 <row> 13189 <entry><literal>%[1y</literal></entry> 13190 <entry>This year</entry> 13191 </row> 13192 <row> 13193 <entry><literal>%[6m</literal></entry> 13194 <entry>In the last 6 months</entry> 13195 </row> 13196 <row> 13197 <entry><literal>%[w</literal></entry> 13198 <entry>This week</entry> 13199 </row> 13200 <row> 13201 <entry><literal>%[d</literal></entry> 13202 <entry>Today</entry> 13203 </row> 13204 <row> 13205 <entry><literal>%[4H</literal></entry> 13206 <entry>In the last 4 hours</entry> 13207 </row> 13208 </tbody> 13209 </tgroup> 13210 </table> 13211 13212 <sect3 id="cond-date-example1"> 13213 <title>Example 1</title> 13214 <para> 13215 We start with a one-condition test. 13216 </para> 13217 13218 <table id="table-cond-date-example1"> 13219 <title>Example 1</title> 13220 <tgroup cols="4"> 13221 <thead> 13222 <row> 13223 <entry>Test</entry> 13224 <entry>Date Range</entry> 13225 <entry>Format String</entry> 13226 <entry>Example</entry> 13227 </row> 13228 </thead> 13229 <tbody> 13230 <row> 13231 <entry><literal>%[1m</literal></entry> 13232 <entry>This month</entry> 13233 <entry><literal>%[%b %d]</literal></entry> 13234 <entry>Dec 10</entry> 13235 </row> 13236 <row> 13237 <entry></entry> 13238 <entry>Older</entry> 13239 <entry><literal>%[%Y-%m-%d]</literal></entry> 13240 <entry>2015-04-23</entry> 13241 </row> 13242 </tbody> 13243 </tgroup> 13244 </table> 13245 <para> 13246 The $index_format string would contain: 13247 </para> 13248 <screen>%?[1m?%[%b %d]&%[%Y-%m-%d]?</screen> 13249 <para> 13250 Reparsed a little, for clarity, you can see the test condition and 13251 the two format strings. 13252 </para> 13253 13254<screen> 13255%?[1m? & ? 13256 13257 %[%b %d] %[%Y-%m-%d] 13258</screen> 13259 13260 </sect3> 13261 13262 <sect3 id="cond-date-example2"> 13263 <title>Example 2</title> 13264 <para> 13265 This example contains three test conditions and four date formats. 13266 </para> 13267 13268 <table id="table-cond-date-example2"> 13269 <title>Example 2</title> 13270 <tgroup cols="4"> 13271 <thead> 13272 <row> 13273 <entry>Test</entry> 13274 <entry>Date Range</entry> 13275 <entry>Format String</entry> 13276 <entry>Example</entry> 13277 </row> 13278 </thead> 13279 <tbody> 13280 <row> 13281 <entry><literal>%[d</literal></entry> 13282 <entry>Today</entry> 13283 <entry><literal>%[%H:%M ]</literal></entry> 13284 <entry>12:34</entry> 13285 </row> 13286 <row> 13287 <entry><literal>%[m</literal></entry> 13288 <entry>This month</entry> 13289 <entry><literal>%[%a %d]</literal></entry> 13290 <entry>Thu 12</entry> 13291 </row> 13292 <row> 13293 <entry><literal>%[y</literal></entry> 13294 <entry>This year</entry> 13295 <entry><literal>%[%b %d]</literal></entry> 13296 <entry>Dec 10</entry> 13297 </row> 13298 <row> 13299 <entry></entry> 13300 <entry>Older</entry> 13301 <entry><literal>%[%m/%y ]</literal></entry> 13302 <entry>06/15</entry> 13303 </row> 13304 </tbody> 13305 </tgroup> 13306 </table> 13307 <para> 13308 The $index_format string would contain: 13309 </para> 13310 13311<screen> 13312%<[y?%<[m?%<[d?%[%H:%M ]&%[%a %d]>&%[%b %d]>&%[%m/%y ]> 13313</screen> 13314 13315 <para> 13316 Reparsed a little, for clarity, you can see the test conditions and 13317 the four format strings. 13318 </para> 13319 13320<screen> 13321%<[y? &%[%m/%y ]> Older 13322 %<[m? &%[%b %d]> This year 13323 %<[d? &%[%a %d]> This month 13324 %[%H:%M ] Today 13325</screen> 13326 13327 <para> 13328 This a another view of the same example, with some whitespace for 13329 clarity. 13330 </para> 13331 13332<screen> 13333%<[y? %<[m? %<[d? AAA & BBB > & CCC > & DDD > 13334</screen> 13335 13336 <literallayout>AAA = %[%H:%M ] BBB = %[%a %d] CCC = %[%b %d] DDD = 13337 %[%m/%y ]</literallayout> 13338 </sect3> 13339 </sect2> 13340 13341 <sect2 id="cond-date-variables"> 13342 <title>Variables</title> 13343 <para> 13344 The <quote>Conditional Dates</quote> feature doesn't have any config 13345 of its own. It modifies the behavior of the format strings. 13346 </para> 13347 </sect2> 13348 13349 <sect2 id="cond-date-neomuttrc"> 13350 <title>neomuttrc</title> 13351 13352<screen> 13353<emphasis role="comment"># Example NeoMutt config file for the cond-date feature.</emphasis> 13354 13355<emphasis role="comment">#</emphasis> 13356<emphasis role="comment"># The default index_format is:</emphasis> 13357<emphasis role="comment"># '%4C %Z %{%b %d} %-15.15L (%?l?%4l&%4c?) %s'</emphasis> 13358<emphasis role="comment">#</emphasis> 13359<emphasis role="comment"># We replace the date field '%{%b %d}', giving:</emphasis> 13360set index_format='%4C %Z %<[y?%<[m?%<[d?%[%H:%M ]&%[%a %d]>&%[%b %d]>&%[%m/%y ]> %-15.15L (%?l?%4l&%4c?) %s' 13361<emphasis role="comment"># Test Date Range Format String Example</emphasis> 13362<emphasis role="comment"># --------------------------------------------</emphasis> 13363<emphasis role="comment"># %[d Today %[%H:%M ] 12:34</emphasis> 13364<emphasis role="comment"># %[m This month %[%a %d] Thu 12</emphasis> 13365<emphasis role="comment"># %[y This year %[%b %d] Dec 10</emphasis> 13366<emphasis role="comment"># — Older %[%m/%y ] 06/15</emphasis> 13367 13368<emphasis role="comment"># vim: syntax=neomuttrc</emphasis> 13369</screen> 13370 13371 </sect2> 13372 13373 <sect2 id="cond-date-see-also"> 13374 <title>See Also</title> 13375 <itemizedlist> 13376 <listitem> 13377 <para> 13378 <link linkend="index-format">$index_format</link> 13379 </para> 13380 </listitem> 13381 <listitem> 13382 <para> 13383 <link linkend="nested-if">nested-if feature</link> 13384 </para> 13385 </listitem> 13386 <listitem> 13387 <para> 13388 <literal>strftime(3)</literal> 13389 </para> 13390 </listitem> 13391 </itemizedlist> 13392 </sect2> 13393 13394 <sect2 id="cond-date-known-bugs"> 13395 <title>Known Bugs</title> 13396 <para> 13397 Date parsing doesn't quite do what you expect. <quote>1w</quote> 13398 doesn't mean the <quote>in the last 7 days</quote>, but 13399 <quote><emphasis>this</emphasis> week</quote>. This doesn't match the 13400 normal NeoMutt behavior: for example <literal>~d>1w</literal> 13401 means emails dated in the last 7 days. 13402 </para> 13403 </sect2> 13404 13405 <sect2 id="cond-date-credits"> 13406 <title>Credits</title> 13407 <para> 13408 Aaron Schrab, Eric Davis, Richard Russon 13409 </para> 13410 </sect2> 13411 </sect1> 13412 13413 <sect1 id="encrypt-to-self"> 13414 <title>Encrypt-to-Self Feature</title> 13415 <subtitle>Save a self-encrypted copy of emails</subtitle> 13416 13417 <sect2 id="encrypt-to-self-support"> 13418 <title>Support</title> 13419 <para> 13420 <emphasis role="bold">Since:</emphasis> NeoMutt 2016-07-23 13421 </para> 13422 <para> 13423 <emphasis role="bold">Dependencies:</emphasis> None 13424 </para> 13425 </sect2> 13426 13427 <sect2 id="encrypt-to-self-intro"> 13428 <title>Introduction</title> 13429 <para> 13430 Once you encrypt an email to someone you cannot read it. This is good 13431 for security, but bad for record-keeping. If you wanted to keep 13432 a copy of an encrypted email you could set 13433 <link linkend="fcc-clear">$fcc_clear</link>. 13434 </para> 13435 <para> 13436 A better option is to enable 13437 <link linkend="smime-self-encrypt">$smime_self_encrypt</link>, then 13438 set <link linkend="smime-default-key">$smime_default_key</link> to 13439 your personal S/MIME key id. 13440 </para> 13441 13442<screen> 13443set smime_self_encrypt = yes 13444set smime_default_key = bb345e23.0 13445</screen> 13446 13447 <para> 13448 Or, if you use PGP, 13449 <link linkend="pgp-self-encrypt">$pgp_self_encrypt</link>, then set 13450 <link linkend="pgp-default-key">$pgp_default_key</link> to your 13451 personal PGP key id. 13452 </para> 13453 13454<screen> 13455set pgp_self_encrypt = yes 13456set pgp_default_key = A4AF18C5582473BD35A1E9CE78BB3D480042198E 13457</screen> 13458 13459 <para> 13460 If you have different key for signing, then you can set 13461 <link linkend="pgp-sign-as">$pgp_sign_as</link> or 13462 <link linkend="smime-sign-as">$smime_sign_as</link> respectively. 13463 </para> 13464 </sect2> 13465 13466 <sect2 id="encrypt-to-self-variables"> 13467 <title>Variables</title> 13468 13469 <table id="table-encrypt-self-variables"> 13470 <title>encrypt-self Variables</title> 13471 <tgroup cols="3"> 13472 <thead> 13473 <row> 13474 <entry>Name</entry> 13475 <entry>Type</entry> 13476 <entry>Default</entry> 13477 </row> 13478 </thead> 13479 <tbody> 13480 <row> 13481 <entry><literal>pgp_default_key</literal></entry> 13482 <entry>string</entry> 13483 <entry>(empty)</entry> 13484 </row> 13485 <row> 13486 <entry><literal>pgp_self_encrypt</literal></entry> 13487 <entry>boolean</entry> 13488 <entry><literal>yes</literal></entry> 13489 </row> 13490 <row> 13491 <entry><literal>pgp_sign_as</literal></entry> 13492 <entry>string</entry> 13493 <entry>(empty)</entry> 13494 </row> 13495 <row> 13496 <entry><literal>smime_default_key</literal></entry> 13497 <entry>string</entry> 13498 <entry>(empty)</entry> 13499 </row> 13500 <row> 13501 <entry><literal>smime_self_encrypt</literal></entry> 13502 <entry>boolean</entry> 13503 <entry><literal>yes</literal></entry> 13504 </row> 13505 <row> 13506 <entry><literal>smime_sign_as</literal></entry> 13507 <entry>string</entry> 13508 <entry>(empty)</entry> 13509 </row> 13510 </tbody> 13511 </tgroup> 13512 </table> 13513 </sect2> 13514 13515 <sect2 id="encrypt-to-self-neomuttrc"> 13516 <title>neomuttrc</title> 13517 13518<screen> 13519<emphasis role="comment"># Example NeoMutt config file for the encrypt-to-self feature.</emphasis> 13520 13521<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 13522<emphasis role="comment"># VARIABLES – shown with their default values</emphasis> 13523<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 13524<emphasis role="comment"># Save a copy of outgoing email, encrypted to yourself</emphasis> 13525set pgp_self_encrypt = "yes" 13526set pgp_default_key = "PGP-KEY" 13527<emphasis role="comment"># set pgp_sign_as = "PGP-SIGNING-KEY"</emphasis> 13528 13529<emphasis role="comment"># Save a copy of outgoing email, encrypted to yourself</emphasis> 13530set smime_self_encrypt = "yes" 13531set smime_default_key = "SMIME-KEY" 13532<emphasis role="comment"># set smime_sign_as = "SMIME-SIGNING-KEY"</emphasis> 13533 13534<emphasis role="comment"># vim: syntax=neomuttrc</emphasis> 13535</screen> 13536 13537 </sect2> 13538 13539 <sect2 id="encrypt-to-self-known-bugs"> 13540 <title>Known Bugs</title> 13541 <para> 13542 None 13543 </para> 13544 </sect2> 13545 13546 <sect2 id="encrypt-to-self-credits"> 13547 <title>Credits</title> 13548 <para> 13549 Omen Wild, Richard Russon, Guillaume Brogi 13550 </para> 13551 </sect2> 13552 </sect1> 13553 13554 <sect1 id="fmemopen"> 13555 <title>Fmemopen Feature</title> 13556 <subtitle>Replace some temporary files with memory buffers</subtitle> 13557 13558 <sect2 id="fmemopen-support"> 13559 <title>Support</title> 13560 <para> 13561 <emphasis role="bold">Since:</emphasis> NeoMutt 2016-03-07 13562 </para> 13563 <variablelist> 13564 <varlistentry> 13565 <term> 13566 <emphasis role="bold">Dependencies:</emphasis> 13567 </term> 13568 <listitem> 13569 <para> 13570 <literal>open_memstream()</literal>, 13571 <literal>fmemopen()</literal> from glibc 13572 </para> 13573 </listitem> 13574 </varlistentry> 13575 </variablelist> 13576 <para> 13577 This feature can be enabled by running <literal>configure</literal> 13578 with the option <literal>--fmemopen</literal> 13579 </para> 13580 </sect2> 13581 13582 <sect2 id="fmemopen-intro"> 13583 <title>Introduction</title> 13584 <para> 13585 The <quote>fmemopen</quote> feature speeds up some searches. 13586 </para> 13587 <para> 13588 This feature changes a few places where NeoMutt creates temporary 13589 files. It replaces them with in-memory buffers. This should improve 13590 the performance when searching the header or body using the 13591 <link linkend="thorough-search">$thorough_search</link> option. 13592 </para> 13593 <para> 13594 There are no user-configurable parts. 13595 </para> 13596 <para> 13597 This feature depends on <literal>open_memstream()</literal> and 13598 <literal>fmemopen()</literal>. They are provided by glibc. Without 13599 them, NeoMutt will simply create temporary files. 13600 </para> 13601 </sect2> 13602 13603 <sect2 id="fmemopen-see-also"> 13604 <title>See Also</title> 13605 <itemizedlist> 13606 <listitem> 13607 <para> 13608 <link linkend="compile-time-features">Compile-Time Features</link> 13609 </para> 13610 </listitem> 13611 <listitem> 13612 <para> 13613 <literal>fmemopen(3)</literal> 13614 </para> 13615 </listitem> 13616 </itemizedlist> 13617 </sect2> 13618 13619 <sect2 id="fmemopen-known-bugs"> 13620 <title>Known Bugs</title> 13621 <para> 13622 <ulink url="https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=834408">debian bug 834408</ulink> 13623 </para> 13624 </sect2> 13625 13626 <sect2 id="fmemopen-credits"> 13627 <title>Credits</title> 13628 <para> 13629 Julius Plenz, Richard Russon 13630 </para> 13631 </sect2> 13632 </sect1> 13633 13634 <sect1 id="forgotten-attachment"> 13635 <title>Forgotten Attachment Feature</title> 13636 <subtitle>Alert user when (s)he forgets to attach a file to an outgoing 13637 email.</subtitle> 13638 13639 <sect2 id="forgotten-attachment-support"> 13640 <title>Support</title> 13641 <para> 13642 <emphasis role="bold">Since:</emphasis> NeoMutt 2016-09-10 13643 </para> 13644 <para> 13645 <emphasis role="bold">Dependencies:</emphasis> None 13646 </para> 13647 </sect2> 13648 13649 <sect2 id="forgotten-attachment-intro"> 13650 <title>Introduction</title> 13651 <para> 13652 The <quote>forgotten-attachment</quote> feature provides a new 13653 setting for NeoMutt that alerts the user if the message body contains 13654 a certain keyword but there are no attachments added. This is meant 13655 to ensure that the user does not forget to attach a file after 13656 promising to do so in the mail. The attachment keyword will not be 13657 scanned in text matched by 13658 <link linkend="quote-regex">$quote_regex</link>. 13659 </para> 13660 </sect2> 13661 13662 <sect2 id="forgotten-attachment-variables"> 13663 <title>Variables</title> 13664 13665 <table id="table-forgotten-attachment-variables"> 13666 <title>forgotten-attachment Variables</title> 13667 <tgroup cols="3"> 13668 <thead> 13669 <row> 13670 <entry>Name</entry> 13671 <entry>Type</entry> 13672 <entry>Default</entry> 13673 </row> 13674 </thead> 13675 <tbody> 13676 <row> 13677 <entry><literal>abort_noattach_regex</literal></entry> 13678 <entry>regular expression</entry> 13679 <entry><literal>\\<(attach|attached|attachments?)\\></literal></entry> 13680 </row> 13681 <row> 13682 <entry><literal>abort_noattach</literal></entry> 13683 <entry>quadoption</entry> 13684 <entry> 13685 <literal>no</literal> 13686 </entry> 13687 </row> 13688 </tbody> 13689 </tgroup> 13690 </table> 13691 </sect2> 13692 13693 <sect2 id="forgotten-attachment-neomuttrc"> 13694 <title>neomuttrc</title> 13695 13696<screen> 13697<emphasis role="comment"># Example NeoMutt config file for the forgotten-attachment feature.</emphasis> 13698 13699<emphasis role="comment"># The 'forgotten-attachment' feature provides a new setting for NeoMutt that</emphasis> 13700<emphasis role="comment"># alerts the user if the message body contains a certain regular expression but there are</emphasis> 13701<emphasis role="comment"># no attachments added. This is meant to ensure that the user does not forget</emphasis> 13702<emphasis role="comment"># to attach a file after promising to do so in the mail.</emphasis> 13703 13704<emphasis role="comment"># Ask if the user wishes to abort sending if $abort_noattach_regex is found in the</emphasis> 13705<emphasis role="comment"># body, but no attachments have been added</emphasis> 13706<emphasis role="comment"># It can be set to:</emphasis> 13707<emphasis role="comment"># "yes" : always abort</emphasis> 13708<emphasis role="comment"># "ask-yes" : ask whether to abort</emphasis> 13709<emphasis role="comment"># "no" : send the mail</emphasis> 13710set abort_noattach = no 13711<emphasis role="comment"># Search for the following regular expression in the body of the email</emphasis> 13712<emphasis role="comment"># English: attach, attached, attachment, attachments</emphasis> 13713set abort_noattach_regex = "\\<attach(|ed|ments?)\\>" 13714<emphasis role="comment"># Nederlands:</emphasis> 13715<emphasis role="comment"># set abort_noattach_regex = "\\<(bijvoegen|bijgevoegd|bijlage|bijlagen)\\>"</emphasis> 13716<emphasis role="comment"># Deutsch:</emphasis> 13717<emphasis role="comment"># set abort_noattach_regex = "\\<(anhängen|angehängt|anhang|anhänge|hängt an)\\>"</emphasis> 13718<emphasis role="comment"># Français:</emphasis> 13719<emphasis role="comment"># set abort_noattach_regex = "\\<(attaché|attachés|attache|attachons|joint|jointe|joints|jointes|joins|joignons)\\>"</emphasis> 13720 13721<emphasis role="comment"># vim: syntax=neomuttrc</emphasis> 13722</screen> 13723 13724 </sect2> 13725 13726 <sect2 id="forgotten-attachment-see-also"> 13727 <title>See Also</title> 13728 <itemizedlist> 13729 <listitem> 13730 <para> 13731 <link linkend="attach-menu">The Attachment Menu</link> 13732 </para> 13733 </listitem> 13734 <listitem> 13735 <para> 13736 <link linkend="attachment-map">The Attachment Menu key mappings</link> 13737 </para> 13738 </listitem> 13739 </itemizedlist> 13740 </sect2> 13741 13742 <sect2 id="forgotten-attachment-known-bugs"> 13743 <title>Known Bugs</title> 13744 <para> 13745 None 13746 </para> 13747 </sect2> 13748 13749 <sect2 id="forgotten-attachment-credits"> 13750 <title>Credits</title> 13751 <para> 13752 Darshit Shah, Richard Russon, Johannes Weißl, Steven Ragnarök 13753 </para> 13754 </sect2> 13755 </sect1> 13756 13757 <sect1 id="global-hooks"> 13758 <title>Global Hooks</title> 13759 <subtitle>Define actions to run globally within NeoMutt</subtitle> 13760 13761 <sect2 id="global-hooks-intro"> 13762 <title>Introduction</title> 13763 <para> 13764 These hooks are called when global events take place in NeoMutt. 13765 </para> 13766 <itemizedlist> 13767 <title>Run a command...</title> 13768 <listitem> 13769 <para> 13770 <emphasis role="bold">timeout-hook</emphasis> – periodically 13771 </para> 13772 </listitem> 13773 <listitem> 13774 <para> 13775 <emphasis role="bold">startup-hook</emphasis> – when NeoMutt 13776 starts up, before opening the first mailbox 13777 </para> 13778 </listitem> 13779 <listitem> 13780 <para> 13781 <emphasis role="bold">shutdown-hook</emphasis> – NeoMutt shuts 13782 down, before closing the last mailbox 13783 </para> 13784 </listitem> 13785 </itemizedlist> 13786 <para> 13787 The commands are NeoMutt commands. If you want to run an external 13788 shell command, you need to run them like this: 13789 </para> 13790<screen> 13791startup-hook 'echo `action.sh ARGS`' 13792</screen> 13793 <para> 13794 The single quotes prevent the 13795 backticks from being expanded. The <literal>echo</literal> command 13796 prevents an empty command error. 13797 </para> 13798 13799 <sect3 id="timeout-hook-intro"> 13800 <title>Timeout Hook</title> 13801 <subtitle>Run a command periodically</subtitle> 13802 <para> 13803 <emphasis role="bold">Since:</emphasis> NeoMutt 2016-08-08 13804 </para> 13805 <para> 13806 This feature implements a new hook that is called periodically when 13807 NeoMutt checks for new mail. This hook is called every 13808 <literal>$timeout</literal> seconds. 13809 </para> 13810 </sect3> 13811 13812 <sect3 id="startup-hook-intro"> 13813 <title>Startup Hook</title> 13814 <subtitle>Run a command when NeoMutt starts up, before opening the 13815 first mailbox</subtitle> 13816 <para> 13817 <emphasis role="bold">Since:</emphasis> NeoMutt 2016-11-25 13818 </para> 13819 <para> 13820 This feature implements a new hook that is called when NeoMutt 13821 first starts up, but before opening the first mailbox. This is most 13822 likely to be useful to users of 13823 <link linkend="notmuch">notmuch</link>. 13824 </para> 13825 </sect3> 13826 13827 <sect3 id="shutdown-hook"> 13828 <title>Shutdown Hook</title> 13829 <subtitle>Run a command when NeoMutt shuts down, before closing the last 13830 mailbox</subtitle> 13831 <para> 13832 <emphasis role="bold">Since:</emphasis> NeoMutt 2016-11-25 13833 </para> 13834 <para> 13835 This feature implements a hook that is called when NeoMutt shuts 13836 down, but before closing the last mailbox. This is most likely to 13837 be useful to users of <link linkend="notmuch">notmuch</link>. 13838 </para> 13839 </sect3> 13840 </sect2> 13841 13842 <sect2 id="global-hooks-commands"> 13843 <title>Commands</title> 13844 <cmdsynopsis> 13845 <command>timeout-hook</command> 13846 <arg choice="plain"> 13847 <replaceable class="parameter">command</replaceable> 13848 </arg> 13849 </cmdsynopsis> 13850 <cmdsynopsis> 13851 <command>startup-hook</command> 13852 <arg choice="plain"> 13853 <replaceable class="parameter">command</replaceable> 13854 </arg> 13855 </cmdsynopsis> 13856 <cmdsynopsis> 13857 <command>shutdown-hook</command> 13858 <arg choice="plain"> 13859 <replaceable class="parameter">command</replaceable> 13860 </arg> 13861 </cmdsynopsis> 13862 </sect2> 13863 13864 <sect2 id="global-hooks-neomuttrc"> 13865 <title>neomuttrc</title> 13866 13867<screen> 13868<emphasis role="comment"># Example NeoMutt config file for the global hooks feature.</emphasis> 13869 13870<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 13871<emphasis role="comment"># COMMANDS – shown with an example argument</emphasis> 13872<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 13873<emphasis role="comment"># After $timeout seconds of inactivity, run this NeoMutt command</emphasis> 13874timeout-hook 'exec sync-mailbox' 13875<emphasis role="comment"># When NeoMutt first loads, run this NeoMutt command</emphasis> 13876startup-hook 'exec sync-mailbox' 13877<emphasis role="comment"># When NeoMutt quits, run this NeoMutt command</emphasis> 13878shutdown-hook 'exec sync-mailbox' 13879 13880<emphasis role="comment"># vim: syntax=neomuttrc</emphasis> 13881</screen> 13882 13883 </sect2> 13884 13885 <sect2 id="timeout-see-also"> 13886 <title>See Also</title> 13887 <itemizedlist> 13888 <listitem> 13889 <para> 13890 <link linkend="timeout">$timeout</link> 13891 </para> 13892 </listitem> 13893 </itemizedlist> 13894 </sect2> 13895 13896 <sect2 id="global-hooks-known-bugs"> 13897 <title>Known Bugs</title> 13898 <para> 13899 None 13900 </para> 13901 </sect2> 13902 13903 <sect2 id="global-hooks-credits"> 13904 <title>Credits</title> 13905 <para> 13906 Armin Wolfermann, Richard Russon, Thomas Adam 13907 </para> 13908 </sect2> 13909 </sect1> 13910 13911 <sect1 id="hccompress"> 13912 <title>Header Cache Compression Feature</title> 13913 <subtitle>Options for compressing the header cache files</subtitle> 13914 13915 <sect2 id="hccompress-support"> 13916 <title>Support</title> 13917 <para> 13918 <emphasis role="bold">Since:</emphasis> NeoMutt 2020-02-22 13919 </para> 13920 <para> 13921 <emphasis role="bold">Dependencies:</emphasis> 13922 <link linkend="caching">header cache</link> 13923 </para> 13924 </sect2> 13925 13926 <sect2 id="hccompress-intro"> 13927 <title>Introduction</title> 13928 <para> 13929 The Header Cache Compression Feature can be used for speeding up the 13930 loading of large mailboxes. Also the space used on disk can be shrunk 13931 by about 50% - depending on the compression method being used. 13932 </para> 13933 <para> 13934 The implementation sits on top of the header caching functions. So the 13935 header cache compression can be used together with all available 13936 database backends. 13937 </para> 13938 </sect2> 13939 13940 <sect2 id="hccompress-variables"> 13941 <title>Variables</title> 13942 <table id="table-hccompress-variables"> 13943 <title>Header Cache Compression Variables</title> 13944 <tgroup cols="3"> 13945 <thead> 13946 <row> 13947 <entry>Name</entry> 13948 <entry>Type</entry> 13949 <entry>Default</entry> 13950 </row> 13951 </thead> 13952 <tbody> 13953 <row> 13954 <entry><literal>header_cache_compress_method</literal></entry> 13955 <entry>string</entry> 13956 <entry>(empty)</entry> 13957 </row> 13958 <row> 13959 <entry><literal>header_cache_compress_level</literal></entry> 13960 <entry>number</entry> 13961 <entry><literal>1</literal></entry> 13962 </row> 13963 </tbody> 13964 </tgroup> 13965 </table> 13966 <para> 13967 The <literal>header_cache_compress_method</literal> can be 13968 <emphasis>(empty)</emphasis> - which means, that no header cache 13969 compression should be used. But when set to <emphasis>lz4</emphasis>, 13970 <emphasis>zlib</emphasis> or <emphasis>zstd</emphasis> - then the 13971 compression is turned on. 13972 </para> 13973 <para> 13974 The <literal>header_cache_compress_level</literal> defines the 13975 compression level, which should be used together with the selected 13976 <literal>header_cache_compress_method</literal>. Here is an overview 13977 of the possible settings: 13978 <table id="table-hccompress-variables-leveldefines"> 13979 <title>Header Cache Compression Methods and it's Levels</title> 13980 <tgroup cols="3"> 13981 <thead> 13982 <row> 13983 <entry>Method Name</entry> 13984 <entry>Min</entry> 13985 <entry>Max</entry> 13986 </row> 13987 </thead> 13988 <tbody> 13989 <row> 13990 <entry><literal>lz4</literal></entry> 13991 <entry>1</entry> 13992 <entry>12</entry> 13993 </row> 13994 <row> 13995 <entry><literal>zlib</literal></entry> 13996 <entry>1</entry> 13997 <entry>9</entry> 13998 </row> 13999 <row> 14000 <entry><literal>zstd</literal></entry> 14001 <entry>1</entry> 14002 <entry>22</entry> 14003 </row> 14004 </tbody> 14005 </tgroup> 14006 </table> 14007 </para> 14008 </sect2> 14009 <sect2 id="hccompress-neomuttrc"> 14010 <title>neomuttrc</title> 14011 14012<screen> 14013<emphasis role="comment"># Example NeoMutt config file for the header cache compression feature.</emphasis> 14014 14015<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 14016<emphasis role="comment"># VARIABLES – shown with their default values</emphasis> 14017<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 14018set header_cache_compress_level = 1 14019set header_cache_compress_method = "" 14020 14021<emphasis role="comment"># vim: syntax=neomuttrc</emphasis> 14022</screen> 14023 14024 </sect2> 14025 14026 <sect2 id="hccompress-known-bugs"> 14027 <title>Known Bugs</title> 14028 <para> 14029 None 14030 </para> 14031 </sect2> 14032 14033 <sect2 id="hccompress-credits"> 14034 <title>Credits</title> 14035 <para> 14036 Tino Reichardt 14037 </para> 14038 </sect2> 14039 </sect1> 14040 14041 <sect1 id="ifdef"> 14042 <title>Ifdef Feature</title> 14043 <subtitle>Conditional config options</subtitle> 14044 14045 <sect2 id="ifdef-support"> 14046 <title>Support</title> 14047 <para> 14048 <emphasis role="bold">Since:</emphasis> NeoMutt 2016-03-07 14049 </para> 14050 <para> 14051 <emphasis role="bold">Dependencies:</emphasis> None 14052 </para> 14053 </sect2> 14054 14055 <sect2 id="ifdef-intro"> 14056 <title>Introduction</title> 14057 <para> 14058 The <quote>ifdef</quote> feature introduces three new commands to 14059 NeoMutt and allow you to share one config file between versions of 14060 NeoMutt that may have different features compiled in. 14061 </para> 14062 14063<screen> 14064ifdef symbol "config-command [args...]" <emphasis role="comment"># If a symbol is defined</emphasis> 14065ifndef symbol "config-command [args...]" <emphasis role="comment"># If a symbol is not defined</emphasis> 14066finish <emphasis role="comment"># Finish reading the current file</emphasis> 14067</screen> 14068 14069 <para> 14070 Here a symbol can be a <link linkend="variables">$variable</link>, 14071 environment variable, 14072 <link linkend="functions"><function></link>, 14073 <link linkend="commands">command</link> or compile-time symbol, such 14074 as <quote>imap</quote>. 14075 </para> 14076 <para> 14077 A list of compile-time symbols can be seen in the output of the 14078 command <screen>neomutt -v</screen> (in the 14079 <quote>Compile options</quote> section). 14080 </para> 14081 <para> 14082 <literal>finish</literal> is particularly useful when combined with 14083 <literal>ifndef</literal>. e.g. 14084 </para> 14085 14086<screen> 14087<emphasis role="comment"># Sidebar config file</emphasis> 14088ifndef sidebar finish 14089</screen> 14090 14091 </sect2> 14092 14093 <sect2 id="ifdef-commands"> 14094 <title>Commands</title> 14095 <cmdsynopsis> 14096 <command>ifdef</command> 14097 <arg choice="plain"> 14098 <replaceable class="parameter">symbol</replaceable> 14099 </arg> 14100 <arg choice="plain"> 14101 <replaceable class="parameter">"config-command [args...]"</replaceable> 14102 </arg> 14103 <command>ifndef</command> 14104 <arg choice="plain"> 14105 <replaceable class="parameter">symbol</replaceable> 14106 </arg> 14107 <arg choice="plain"> 14108 <replaceable class="parameter">"config-command [args...]"</replaceable> 14109 </arg> 14110 <command>finish</command> 14111 </cmdsynopsis> 14112 </sect2> 14113 14114 <sect2 id="ifdef-neomuttrc"> 14115 <title>neomuttrc</title> 14116 14117<screen> 14118<emphasis role="comment"># Example NeoMutt config file for the ifdef feature.</emphasis> 14119 14120<emphasis role="comment"># This feature introduces three useful commands which allow you to share</emphasis> 14121<emphasis role="comment"># one config file between versions of NeoMutt that may have different</emphasis> 14122<emphasis role="comment"># features compiled in.</emphasis> 14123 14124<emphasis role="comment"># ifdef symbol "config-command [args...]"</emphasis> 14125<emphasis role="comment"># ifndef symbol "config-command [args...]"</emphasis> 14126<emphasis role="comment"># finish</emphasis> 14127<emphasis role="comment"># The 'ifdef' command tests whether NeoMutt understands the name of</emphasis> 14128<emphasis role="comment"># a variable, environment variable, function, command or compile-time symbol.</emphasis> 14129 14130<emphasis role="comment"># If it does, then it executes a config command.</emphasis> 14131 14132<emphasis role="comment"># The 'ifndef' command tests whether a symbol does NOT exist.</emphasis> 14133 14134<emphasis role="comment"># The 'finish' command tells NeoMutt to stop reading current config file.</emphasis> 14135 14136<emphasis role="comment"># If the 'trash' variable exists, set it.</emphasis> 14137ifdef trash 'set trash=~/Mail/trash' 14138<emphasis role="comment"># If the 'PS1' environment variable exists, source config file.</emphasis> 14139ifdef PS1 'source .neomutt/interactive.rc' 14140<emphasis role="comment"># If the 'tag-pattern' function exists, bind a key to it.</emphasis> 14141ifdef tag-pattern 'bind index <F6> tag-pattern' 14142<emphasis role="comment"># If the 'imap-fetch-mail' command exists, read my IMAP config.</emphasis> 14143ifdef imap-fetch-mail 'source ~/.neomutt/imap.rc' 14144<emphasis role="comment"># If the compile-time symbol 'sidebar' does not exist, then</emphasis> 14145<emphasis role="comment"># stop reading the current config file.</emphasis> 14146ifndef sidebar finish 14147 14148<emphasis role="comment"># vim: syntax=neomuttrc</emphasis> 14149</screen> 14150 14151 </sect2> 14152 14153 <sect2 id="ifdef-known-bugs"> 14154 <title>Known Bugs</title> 14155 <para> 14156 None 14157 </para> 14158 </sect2> 14159 14160 <sect2 id="ifdef-credits"> 14161 <title>Credits</title> 14162 <para> 14163 Cedric Duval, Matteo F. Vescovi, Richard Russon 14164 </para> 14165 </sect2> 14166 </sect1> 14167 14168 <sect1 id="index-color"> 14169 <title>Index Color Feature</title> 14170 <subtitle>Custom rules for theming the email index</subtitle> 14171 14172 <sect2 id="index-color-support"> 14173 <title>Support</title> 14174 <para> 14175 <emphasis role="bold">Since:</emphasis> NeoMutt 2016-03-07 14176 </para> 14177 <variablelist> 14178 <varlistentry> 14179 <term> 14180 <emphasis role="bold">Dependencies:</emphasis> 14181 </term> 14182 <listitem> 14183 <para> 14184 <link linkend="status-color">status-color feature</link> 14185 </para> 14186 </listitem> 14187 </varlistentry> 14188 </variablelist> 14189 </sect2> 14190 14191 <sect2 id="index-color-intro"> 14192 <title>Introduction</title> 14193 <para> 14194 The <quote>index-color</quote> feature allows you to specify colors 14195 for individual parts of the email index. e.g. Subject, Author, Flags. 14196 </para> 14197 <para> 14198 First choose which part of the index you'd like to color. Then, if 14199 needed, pick a pattern to match. 14200 </para> 14201 <para> 14202 Note: The pattern does not have to refer to the object you wish to 14203 color. e.g. 14204 </para> 14205 <screen>color index_author red default "~sneomutt"</screen> 14206 <para> 14207 The author appears red when the subject (~s) contains 14208 <quote>neomutt</quote>. 14209 </para> 14210 </sect2> 14211 14212 <sect2 id="index-color-colors"> 14213 <title>Colors</title> 14214 <para> 14215 All the colors default to <literal>default</literal>, i.e. unset. 14216 </para> 14217 <para> 14218 The index objects can be themed using the <literal>color</literal> 14219 command. Some objects require a pattern. 14220 </para> 14221 14222<screen> 14223color index-object foreground background 14224color index-object foreground background pattern 14225</screen> 14226 14227 <table id="table-index-color-colors"> 14228 <title>Index Colors</title> 14229 <tgroup cols="3"> 14230 <thead> 14231 <row> 14232 <entry>Object</entry> 14233 <entry>Pattern</entry> 14234 <entry>Highlights</entry> 14235 </row> 14236 </thead> 14237 <tbody> 14238 <row> 14239 <entry><literal>index</literal></entry> 14240 <entry>yes</entry> 14241 <entry>Entire index line</entry> 14242 </row> 14243 <row> 14244 <entry><literal>index_author</literal></entry> 14245 <entry>yes</entry> 14246 <entry>Author name, %A %a %F %L %n</entry> 14247 </row> 14248 <row> 14249 <entry><literal>index_collapsed</literal></entry> 14250 <entry>no</entry> 14251 <entry>Number of messages in a collapsed thread, %M</entry> 14252 </row> 14253 <row> 14254 <entry><literal>index_date</literal></entry> 14255 <entry>no</entry> 14256 <entry>Date field</entry> 14257 </row> 14258 <row> 14259 <entry><literal>index_flags</literal></entry> 14260 <entry>yes</entry> 14261 <entry>Message flags, %S %Z</entry> 14262 </row> 14263 <row> 14264 <entry><literal>index_label</literal></entry> 14265 <entry>no</entry> 14266 <entry>Message label, %y %Y</entry> 14267 </row> 14268 <row> 14269 <entry><literal>index_number</literal></entry> 14270 <entry>no</entry> 14271 <entry>Message number, %C</entry> 14272 </row> 14273 <row> 14274 <entry><literal>index_size</literal></entry> 14275 <entry>no</entry> 14276 <entry>Message size, %c %cr %l</entry> 14277 </row> 14278 <row> 14279 <entry><literal>index_subject</literal></entry> 14280 <entry>yes</entry> 14281 <entry>Subject, %s</entry> 14282 </row> 14283 </tbody> 14284 </tgroup> 14285 </table> 14286 </sect2> 14287 14288 <sect2 id="index-color-neomuttrc"> 14289 <title>neomuttrc</title> 14290 14291<screen> 14292<emphasis role="comment"># Example NeoMutt config file for the index-color feature.</emphasis> 14293 14294<emphasis role="comment"># Entire index line</emphasis> 14295color index white black '.*' 14296<emphasis role="comment"># Author name, %A %a %F %L %n</emphasis> 14297<emphasis role="comment"># Give the author column a dark grey background</emphasis> 14298color index_author default color234 '.*' 14299<emphasis role="comment"># Highlight a particular from (~f)</emphasis> 14300color index_author brightyellow color234 '~fRay Charles' 14301<emphasis role="comment"># Message flags, %S %Z</emphasis> 14302<emphasis role="comment"># Highlight the flags for flagged (~F) emails</emphasis> 14303color index_flags default red '~F' 14304<emphasis role="comment"># Subject, %s</emphasis> 14305<emphasis role="comment"># Look for a particular subject (~s)</emphasis> 14306color index_subject brightcyan default '~s\(closes #[0-9]+\)' 14307<emphasis role="comment"># Number of messages in a collapsed thread, %M</emphasis> 14308color index_collapsed default brightblue 14309<emphasis role="comment"># Date field</emphasis> 14310color index_date green default 14311<emphasis role="comment"># Message label, %y %Y</emphasis> 14312color index_label default brightgreen 14313<emphasis role="comment"># Message number, %C</emphasis> 14314color index_number red default 14315<emphasis role="comment"># Message size, %c %cr %l</emphasis> 14316color index_size cyan default 14317 14318<emphasis role="comment"># vim: syntax=neomuttrc</emphasis> 14319</screen> 14320 14321 </sect2> 14322 14323 <sect2 id="index-color-see-also"> 14324 <title>See Also</title> 14325 <itemizedlist> 14326 <listitem> 14327 <para> 14328 <link linkend="regex">Regular Expressions</link> 14329 </para> 14330 </listitem> 14331 <listitem> 14332 <para> 14333 <link linkend="patterns">Patterns</link> 14334 </para> 14335 </listitem> 14336 <listitem> 14337 <para> 14338 <link linkend="index-format">$index_format</link> 14339 </para> 14340 </listitem> 14341 <listitem> 14342 <para> 14343 <link linkend="color">Color command</link> 14344 </para> 14345 </listitem> 14346 <listitem> 14347 <para> 14348 <link linkend="status-color">Status-Color feature</link> 14349 </para> 14350 </listitem> 14351 </itemizedlist> 14352 </sect2> 14353 14354 <sect2 id="index-color-known-bugs"> 14355 <title>Known Bugs</title> 14356 <para> 14357 None 14358 </para> 14359 </sect2> 14360 14361 <sect2 id="index-color-credits"> 14362 <title>Credits</title> 14363 <para> 14364 Christian Aichinger, Christoph <quote>Myon</quote> Berg, 14365 Elimar Riesebieter, Eric Davis, Vladimir Marek, Richard Russon 14366 </para> 14367 </sect2> 14368 </sect1> 14369 14370 <sect1 id="initials"> 14371 <title>Initials Expando Feature</title> 14372 <subtitle>Expando for author's initials</subtitle> 14373 14374 <sect2 id="initials-support"> 14375 <title>Support</title> 14376 <para> 14377 <emphasis role="bold">Since:</emphasis> NeoMutt 2016-03-07 14378 </para> 14379 <para> 14380 <emphasis role="bold">Dependencies:</emphasis> None 14381 </para> 14382 </sect2> 14383 14384 <sect2 id="initials-intro"> 14385 <title>Introduction</title> 14386 <para> 14387 The <quote>initials</quote> feature adds an expando (%I) for an 14388 author's initials. 14389 </para> 14390 <para> 14391 The index panel displays a list of emails. Its layout is controlled 14392 by the <link linkend="index-format">$index_format</link> variable. 14393 Using this expando saves space in the index panel. This can be useful 14394 if you are regularly working with a small set of people. 14395 </para> 14396 </sect2> 14397 14398 <sect2 id="initials-variables"> 14399 <title>Variables</title> 14400 <para> 14401 This feature has no config of its own. It adds an expando which can 14402 be used in the <link linkend="index-format">$index_format</link> 14403 variable. 14404 </para> 14405 </sect2> 14406 14407 <sect2 id="initials-neomuttrc"> 14408 <title>neomuttrc</title> 14409 14410<screen> 14411<emphasis role="comment"># Example NeoMutt config file for the initials feature.</emphasis> 14412 14413<emphasis role="comment"># The 'initials' feature has no config of its own.</emphasis> 14414 14415<emphasis role="comment"># It adds an expando for an author's initials,</emphasis> 14416<emphasis role="comment"># which can be used in the 'index_format' variable.</emphasis> 14417 14418<emphasis role="comment"># The default 'index_format' is:</emphasis> 14419set index_format='%4C %Z %{%b %d} %-15.15L (%?l?%4l&%4c?) %s' 14420<emphasis role="comment"># Where %L represents the author/recipient</emphasis> 14421<emphasis role="comment"># This might look like:</emphasis> 14422<emphasis role="comment"># 1 + Nov 17 David Bowie Changesbowie ( 689)</emphasis> 14423<emphasis role="comment"># 2 ! Nov 17 Stevie Nicks Rumours ( 555)</emphasis> 14424<emphasis role="comment"># 3 + Nov 16 Jimi Hendrix Voodoo Child ( 263)</emphasis> 14425<emphasis role="comment"># 4 + Nov 16 Debbie Harry Parallel Lines ( 540)</emphasis> 14426<emphasis role="comment"># Using the %I expando:</emphasis> 14427set index_format='%4C %Z %{%b %d} %I (%?l?%4l&%4c?) %s' 14428<emphasis role="comment"># This might look like:</emphasis> 14429<emphasis role="comment"># 1 + Nov 17 DB Changesbowie ( 689)</emphasis> 14430<emphasis role="comment"># 2 ! Nov 17 SN Rumours ( 555)</emphasis> 14431<emphasis role="comment"># 3 + Nov 16 JH Voodoo Child ( 263)</emphasis> 14432<emphasis role="comment"># 4 + Nov 16 DH Parallel Lines ( 540)</emphasis> 14433 14434<emphasis role="comment"># vim: syntax=neomuttrc</emphasis> 14435</screen> 14436 14437 </sect2> 14438 14439 <sect2 id="initials-see-also"> 14440 <title>See Also</title> 14441 <itemizedlist> 14442 <listitem> 14443 <para> 14444 <link linkend="index-format">$index_format</link> 14445 </para> 14446 </listitem> 14447 <listitem> 14448 <para> 14449 <link linkend="index-color">index-color feature</link> 14450 </para> 14451 </listitem> 14452 <listitem> 14453 <para> 14454 <link linkend="folder-hook">folder-hook</link> 14455 </para> 14456 </listitem> 14457 </itemizedlist> 14458 </sect2> 14459 14460 <sect2 id="initials-known-bugs"> 14461 <title>Known Bugs</title> 14462 <para> 14463 None 14464 </para> 14465 </sect2> 14466 14467 <sect2 id="initials-credits"> 14468 <title>Credits</title> 14469 <para> 14470 Vsevolod Volkov, Richard Russon 14471 </para> 14472 </sect2> 14473 </sect1> 14474 14475 <sect1 id="kyoto-cabinet"> 14476 <title>Kyoto Cabinet Feature</title> 14477 <subtitle>Kyoto Cabinet backend for the header cache</subtitle> 14478 14479 <sect2 id="kyoto-cabinet-support"> 14480 <title>Support</title> 14481 <para> 14482 <emphasis role="bold">Since:</emphasis> NeoMutt 2016-10-02 14483 </para> 14484 <variablelist> 14485 <varlistentry> 14486 <term> 14487 <emphasis role="bold">Dependencies:</emphasis> 14488 </term> 14489 <listitem> 14490 <para> 14491 <ulink url="http://fallabs.com/kyotocabinet/">Kyoto Cabinet libraries</ulink> 14492 </para> 14493 </listitem> 14494 </varlistentry> 14495 </variablelist> 14496 <para> 14497 To check if NeoMutt supports Kyoto Cabinet, look for 14498 </para> 14499 <itemizedlist> 14500 <listitem> 14501 <para> 14502 <quote>kyoto</quote> in the NeoMutt version. 14503 </para> 14504 </listitem> 14505 <listitem> 14506 <para> 14507 <quote>+hcache</quote> in the compile options 14508 </para> 14509 </listitem> 14510 <listitem> 14511 <para> 14512 <quote>hcache backend: kyotocabinet</quote> in the NeoMutt 14513 version 14514 </para> 14515 </listitem> 14516 </itemizedlist> 14517 </sect2> 14518 14519 <sect2 id="kyoto-cabinet-intro"> 14520 <title>Introduction</title> 14521 <para> 14522 This feature adds support for using Kyoto Cabinet, the successor to 14523 Tokyo Cabinet, as a storage backend for NeoMutt's header cache 14524 (hcache). It is enabled at configure time with the 14525 <emphasis>--with-kyotocabinet=<path></emphasis> switch. 14526 </para> 14527 </sect2> 14528 14529 <sect2 id="kyoto-cabinet-see-also"> 14530 <title>See Also</title> 14531 <itemizedlist> 14532 <listitem> 14533 <para> 14534 <link linkend="caching">Local Caching</link> 14535 </para> 14536 </listitem> 14537 <listitem> 14538 <para> 14539 <ulink url="http://fallabs.com/kyotocabinet/">Kyoto Cabinet</ulink> 14540 </para> 14541 </listitem> 14542 </itemizedlist> 14543 </sect2> 14544 14545 <sect2 id="kyoto-cabinet-known-bugs"> 14546 <title>Known Bugs</title> 14547 <para> 14548 None 14549 </para> 14550 </sect2> 14551 14552 <sect2 id="kyoto-cabinet-credits"> 14553 <title>Credits</title> 14554 <para> 14555 Clemens Lang 14556 </para> 14557 </sect2> 14558 </sect1> 14559 14560 <sect1 id="limit-current-thread"> 14561 <title>Limit Current Thread Feature</title> 14562 <subtitle>Focus on one Email Thread</subtitle> 14563 14564 <sect2 id="limit-current-thread-support"> 14565 <title>Support</title> 14566 <para> 14567 <emphasis role="bold">Since:</emphasis> NeoMutt 2016-03-28 14568 </para> 14569 <para> 14570 <emphasis role="bold">Dependencies:</emphasis> None 14571 </para> 14572 </sect2> 14573 14574 <sect2 id="limit-current-thread-intro"> 14575 <title>Introduction</title> 14576 <para> 14577 This feature adds a new way of using the 14578 <link linkend="tuning-search">Limit Command</link>. The 14579 <literal><limit-current-thread></literal> function restricts 14580 the view to just the current thread. Setting the limit (the 14581 <literal>l</literal> key) to <quote>all</quote> will restore the full 14582 email list. 14583 </para> 14584 </sect2> 14585 14586 <sect2 id="limit-current-thread-functions"> 14587 <title>Functions</title> 14588 <para> 14589 Limit-current-thread adds the following function to NeoMutt. By 14590 default, it is not bound to a key. 14591 </para> 14592 14593 <table id="table-limit-current-thread-functions"> 14594 <title>Limit-Current-Thread Functions</title> 14595 <tgroup cols="3"> 14596 <thead> 14597 <row> 14598 <entry>Menus</entry> 14599 <entry>Function</entry> 14600 <entry>Description</entry> 14601 </row> 14602 </thead> 14603 <tbody> 14604 <row> 14605 <entry>index</entry> 14606 <entry><literal><limit-current-thread></literal></entry> 14607 <entry>Limit view to current thread</entry> 14608 </row> 14609 </tbody> 14610 </tgroup> 14611 </table> 14612 </sect2> 14613 14614 <sect2 id="limit-current-thread-neomuttrc"> 14615 <title>neomuttrc</title> 14616 14617<screen> 14618<emphasis role="comment"># Example NeoMutt config file for the limit-current-thread feature.</emphasis> 14619 14620<emphasis role="comment"># Limit view to current thread</emphasis> 14621bind index <esc>L limit-current-thread 14622 14623<emphasis role="comment"># vim: syntax=neomuttrc</emphasis> 14624</screen> 14625 14626 </sect2> 14627 14628 <sect2 id="limit-current-thread-known-bugs"> 14629 <title>Known Bugs</title> 14630 <para> 14631 None 14632 </para> 14633 </sect2> 14634 14635 <sect2 id="limit-current-thread-credits"> 14636 <title>Credits</title> 14637 <para> 14638 David Sterba, Richard Russon 14639 </para> 14640 </sect2> 14641 </sect1> 14642 14643 <sect1 id="lmdb"> 14644 <title>LMDB Feature</title> 14645 <subtitle>LMDB backend for the header cache</subtitle> 14646 14647 <sect2 id="lmdb-support"> 14648 <title>Support</title> 14649 <para> 14650 <emphasis role="bold">Since:</emphasis> NeoMutt 2016-07-23 14651 </para> 14652 <para> 14653 <emphasis role="bold">Dependencies:</emphasis> None 14654 </para> 14655 </sect2> 14656 14657 <sect2 id="lmdb-intro"> 14658 <title>Introduction</title> 14659 <para> 14660 This feature adds support for using LMDB as a storage backend for 14661 NeoMutt's header cache (hcache). It is enabled at configure time with 14662 the <emphasis>--with-lmdb=<path></emphasis> switch. 14663 </para> 14664 <note> 14665 <para> 14666 It is not recommended to store the lmdb database on a shared drive. 14667 </para> 14668 </note> 14669 </sect2> 14670 14671 <sect2 id="lmdb-see-also"> 14672 <title>See Also</title> 14673 <itemizedlist> 14674 <listitem> 14675 <para> 14676 <link linkend="caching">Local Caching</link> 14677 </para> 14678 </listitem> 14679 </itemizedlist> 14680 </sect2> 14681 14682 <sect2 id="lmdb-known-bugs"> 14683 <title>Known Bugs</title> 14684 <para> 14685 None 14686 </para> 14687 </sect2> 14688 14689 <sect2 id="lmdb-credits"> 14690 <title>Credits</title> 14691 <para> 14692 Pietro Cerutti, Jan-Piet Mens, Clemens Lang 14693 </para> 14694 </sect2> 14695 </sect1> 14696 14697 <sect1 id="multiple-fcc"> 14698 <title>Multiple FCC Feature</title> 14699 <subtitle>Save multiple copies of outgoing mail</subtitle> 14700 14701 <sect2 id="multiple-fcc-support"> 14702 <title>Support</title> 14703 <para> 14704 <emphasis role="bold">Since:</emphasis> NeoMutt 2016-08-08 14705 </para> 14706 <para> 14707 <emphasis role="bold">Dependencies:</emphasis> None 14708 </para> 14709 </sect2> 14710 14711 <sect2 id="multiple-fcc-intro"> 14712 <title>Introduction</title> 14713 <para> 14714 This feature allows the user to save outgoing emails in multiple 14715 folders. 14716 </para> 14717 <para> 14718 Folders should be listed separated by commas, 14719 <emphasis role="bold">but no spaces</emphasis>. 14720 </para> 14721 <para> 14722 The <quote>fcc</quote> field of an email can be set in two ways: 14723 </para> 14724 <itemizedlist> 14725 <listitem> 14726 <para> 14727 The <edit-fcc> command in the compose menu (default key: 14728 <quote>f</quote>) 14729 </para> 14730 </listitem> 14731 <listitem> 14732 <para> 14733 Creating a <literal>fcc-hook</literal> in your 14734 <literal>.neomuttrc</literal> 14735 </para> 14736 </listitem> 14737 </itemizedlist> 14738 </sect2> 14739 14740 <sect2 id="multiple-fcc-see-also"> 14741 <title>See Also</title> 14742 <itemizedlist> 14743 <listitem> 14744 <para> 14745 <link linkend="record">$record</link> 14746 </para> 14747 </listitem> 14748 <listitem> 14749 <para> 14750 <link linkend="fcc-hook">fcc-hook</link> 14751 </para> 14752 </listitem> 14753 </itemizedlist> 14754 </sect2> 14755 14756 <sect2 id="multiple-fcc-known-bugs"> 14757 <title>Known Bugs</title> 14758 <para> 14759 None 14760 </para> 14761 </sect2> 14762 14763 <sect2 id="multiple-fcc-credits"> 14764 <title>Credits</title> 14765 <para> 14766 Omen Wild, Richard Russon 14767 </para> 14768 </sect2> 14769 </sect1> 14770 14771 <sect1 id="nested-if"> 14772 <title>Nested If Feature</title> 14773 <subtitle>Allow complex nested conditions in format strings</subtitle> 14774 14775 <sect2 id="nested-if-support"> 14776 <title>Support</title> 14777 <para> 14778 <emphasis role="bold">Since:</emphasis> NeoMutt 2016-03-07 14779 </para> 14780 <para> 14781 <emphasis role="bold">Dependencies:</emphasis> None 14782 </para> 14783 </sect2> 14784 14785 <sect2 id="nested-if-intro"> 14786 <title>Introduction</title> 14787 <para> 14788 NeoMutt's format strings can contain embedded if-then-else 14789 conditions. They are of the form: 14790 </para> 14791 <screen>%?VAR?TRUE&FALSE?</screen> 14792 <para> 14793 If the variable <quote>VAR</quote> has a value greater than zero, 14794 print the <quote>TRUE</quote> string, otherwise print the 14795 <quote>FALSE</quote> string. 14796 </para> 14797 <para> 14798 e.g. <literal>%?S?Size: %S&Empty?</literal> 14799 </para> 14800 <para> 14801 Which can be read as: 14802 </para> 14803 <literallayout>if (%S > 0) { print "Size: %S" } else { print "Empty" }</literallayout> 14804 <para> 14805 These conditions are useful, but in NeoMutt they cannot be nested 14806 within one another. This feature uses the notation 14807 <literal>%<VAR?TRUE&FALSE></literal> and allows them to be 14808 nested. 14809 </para> 14810 <para> 14811 The <literal>%<...></literal> notation was used to format the 14812 current local time. but that's not really very useful since NeoMutt 14813 has no means of refreshing the screen periodically. 14814 </para> 14815 <para> 14816 A simple nested condition might be: (Some whitespace has been 14817 introduced for clarity) 14818 </para> 14819 14820<screen> 14821%<x? %<y? XY & X > & %<y? Y & NONE > > Conditions 14822 %<y? XY & X > x>0 14823 XY x>0,y>0 14824 X x>0,y=0 14825</screen> 14826 14827<screen> 14828%<x? %<y? XY & X > & %<y? Y & NONE > > Conditions 14829 %<y? Y & NONE > x=0 14830 Y x=0,y>0 14831 NONE x=0,y=0 14832</screen> 14833 14834 <para> 14835 Equivalent to: 14836 </para> 14837 <literallayout>if (x > 0) { 14838 if (y > 0) { 14839 print 'XY' 14840 } else { 14841 print 'X' 14842 } 14843} else { 14844 if (y > 0) { 14845 print 'Y' 14846 } else { 14847 print 'NONE' 14848 } 14849}</literallayout> 14850 <para> 14851 Examples: 14852 </para> 14853 14854<screen> 14855set index_format='%4C %Z %{%b %d} %-25.25n %s%> %<M?%M Msgs &%<l?%l Lines&%c Bytes>>' 14856</screen> 14857 14858 <literallayout>if a thread is folded display the number of messages (%M) 14859else if we know how many lines in the message display lines in message (%l) 14860else display the size of the message in bytes (%c)</literallayout> 14861 14862<screen> 14863set index_format='%4C %Z %{%b %d} %-25.25n %<M?[%M] %s&%s%* %<l?%l&%c>>' 14864</screen> 14865 14866 <literallayout>if a thread is folded display the number of messages (%M) and the subject (%s) 14867else if we know how many lines are in the message display subject (%s) and the lines in message (%l) 14868else display the subject (%s) and the size of the message in bytes (%c)</literallayout> 14869 14870 <note> 14871 <para> 14872 If you wish to use angle brackets <literal>< ></literal> in 14873 a nested condition, then it's necessary to escape them, e.g. 14874 </para> 14875 <screen>set index_format='%<M?\<%M\>&%s>'</screen> 14876 </note> 14877 </sect2> 14878 14879 <sect2 id="nested-if-variables"> 14880 <title>Variables</title> 14881 <para> 14882 The <quote>nested-if</quote> feature doesn't have any config of its 14883 own. It modifies the behavior of the format strings. 14884 </para> 14885 </sect2> 14886 14887 <sect2 id="nested-if-neomuttrc"> 14888 <title>neomuttrc</title> 14889 14890<screen> 14891<emphasis role="comment"># Example NeoMutt config file for the nested-if feature.</emphasis> 14892 14893<emphasis role="comment"># This feature uses the format: '%<VAR?TRUE&FALSE>' for conditional</emphasis> 14894<emphasis role="comment"># format strings that can be nested.</emphasis> 14895 14896<emphasis role="comment"># Example 1</emphasis> 14897<emphasis role="comment"># if a thread is folded</emphasis> 14898<emphasis role="comment"># display the number of messages (%M)</emphasis> 14899<emphasis role="comment"># else if we know how many lines in the message</emphasis> 14900<emphasis role="comment"># display lines in message (%l)</emphasis> 14901<emphasis role="comment"># else display the size of the message in bytes (%c)</emphasis> 14902set index_format='%4C %Z %{%b %d} %-25.25n %s%> %<M?%M Msgs &%<l?%l Lines&%c Bytes>>' 14903 14904<emphasis role="comment"># Example 2</emphasis> 14905<emphasis role="comment"># if a thread is folded</emphasis> 14906<emphasis role="comment"># display the number of messages (%M)</emphasis> 14907<emphasis role="comment"># display the subject (%s)</emphasis> 14908<emphasis role="comment"># else if we know how many lines in the message</emphasis> 14909<emphasis role="comment"># display lines in message (%l)</emphasis> 14910<emphasis role="comment"># else</emphasis> 14911<emphasis role="comment"># display the size of the message in bytes (%c)</emphasis> 14912set index_format='%4C %Z %{%b %d} %-25.25n %<M?[%M] %s&%s%* %<l?%l&%c>>' 14913 14914<emphasis role="comment"># vim: syntax=neomuttrc</emphasis> 14915</screen> 14916 14917 </sect2> 14918 14919 <sect2 id="nested-if-see-also"> 14920 <title>See Also</title> 14921 <itemizedlist> 14922 <listitem> 14923 <para> 14924 <link linkend="cond-date">cond-date feature</link> 14925 </para> 14926 </listitem> 14927 <listitem> 14928 <para> 14929 <link linkend="index-format">$index_format</link> 14930 </para> 14931 </listitem> 14932 <listitem> 14933 <para> 14934 <link linkend="status-format">$status_format</link> 14935 </para> 14936 </listitem> 14937 </itemizedlist> 14938 </sect2> 14939 14940 <sect2 id="nested-if-known-bugs"> 14941 <title>Known Bugs</title> 14942 <para> 14943 This feature is hard to understand 14944 </para> 14945 </sect2> 14946 14947 <sect2 id="nested-if-credits"> 14948 <title>Credits</title> 14949 <para> 14950 David Champion, Richard Russon, Aleksa Sarai 14951 </para> 14952 </sect2> 14953 </sect1> 14954 14955 <sect1 id="new-mail-hook"> 14956 <title>New Mail Feature</title> 14957 <subtitle>Execute a command upon the receipt of new mail.</subtitle> 14958 14959 <sect2 id="new-mail-support"> 14960 <title>Support</title> 14961 <para> 14962 <emphasis role="bold">Since:</emphasis> NeoMutt 2016-07-23 14963 </para> 14964 <para> 14965 <emphasis role="bold">Dependencies:</emphasis> None 14966 </para> 14967 </sect2> 14968 14969 <sect2 id="new-mail-intro"> 14970 <title>Introduction</title> 14971 <para> 14972 This feature enables the new_mail_command setting, which can be used 14973 to execute a custom script (e.g. a notification handler) upon 14974 receiving a new mail. 14975 </para> 14976 <para> 14977 The command string can contain expandos, such as 14978 <literal>%n</literal> for the number of new messages. For a complete 14979 list, see: <link linkend="status-format">$status_format</link>. 14980 </para> 14981 <note> 14982 <para> 14983 When the notification is sent, the folder of the new mail is no 14984 longer known. This is a limitation of NeoMutt. The `%f` expando 14985 will show the open folder. 14986 </para> 14987 <para> 14988 When using Maildir local mailboxes, you must set 14989 <link linkend="check-new">$check_new</link> config variable for 14990 this feature to work. 14991 </para> 14992 </note> 14993 <para> 14994 For example in Linux you can use (most distributions already provide 14995 notify-send): 14996 </para> 14997 14998<screen> 14999set new_mail_command="notify-send --icon='/home/santiago/Pictures/neomutt.png' \ 15000 'New Email' '%n new messages, %u unread.' &" 15001</screen> 15002 15003 <para> 15004 And in OS X you will need to install a command line interface for 15005 Notification Center, for example 15006 <ulink url="https://github.com/julienXX/terminal-notifier">terminal-notifier</ulink>: 15007 </para> 15008 15009<screen> 15010set new_mail_command="terminal-notifier -title '%v' -subtitle 'New Mail' \ 15011 -message '%n new messages, %u unread.' -activate 'com.apple.Terminal'" 15012</screen> 15013 15014 </sect2> 15015 15016 <sect2 id="new-mail-variables"> 15017 <title>Variables</title> 15018 15019 <table id="table-new-mail-variables"> 15020 <title>New Mail Command Variables</title> 15021 <tgroup cols="3"> 15022 <thead> 15023 <row> 15024 <entry>Name</entry> 15025 <entry>Type</entry> 15026 <entry>Default</entry> 15027 </row> 15028 </thead> 15029 <tbody> 15030 <row> 15031 <entry><literal>new_mail_command</literal></entry> 15032 <entry>string</entry> 15033 <entry>(empty)</entry> 15034 </row> 15035 </tbody> 15036 </tgroup> 15037 </table> 15038 </sect2> 15039 15040 <sect2 id="new-mail-neomuttrc"> 15041 <title>neomuttrc</title> 15042 15043<screen> 15044<emphasis role="comment"># Example NeoMutt config file for the new-mail feature.</emphasis> 15045 15046<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 15047<emphasis role="comment"># VARIABLES – shown with their default values</emphasis> 15048<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 15049<emphasis role="comment"># Set the command you want NeoMutt to execute upon the receipt of a new email</emphasis> 15050set new_mail_command = "" 15051<emphasis role="comment"># Linux example:</emphasis> 15052<emphasis role="comment"># set new_command="notify-send --icon='/home/santiago/Pictures/neomutt.png' \</emphasis> 15053<emphasis role="comment"># 'New Email in %f' '%n new messages, %u unread.' &"</emphasis> 15054<emphasis role="comment"># OS X example:</emphasis> 15055<emphasis role="comment"># set new_mail_command="terminal-notifier -title '%v' -subtitle 'New Mail in %f' \</emphasis> 15056<emphasis role="comment"># -message '%n new messages, %u unread.' -activate 'com.apple.Terminal'"</emphasis> 15057<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 15058 15059<emphasis role="comment"># vim: syntax=neomuttrc</emphasis> 15060</screen> 15061 15062 </sect2> 15063 15064 <sect2 id="new-mail-see-also"> 15065 <title>See Also</title> 15066 <itemizedlist> 15067 <listitem> 15068 <para> 15069 <link linkend="folder-hook">folder-hook</link> 15070 </para> 15071 </listitem> 15072 </itemizedlist> 15073 </sect2> 15074 15075 <sect2 id="new-mail-known-bugs"> 15076 <title>Known Bugs</title> 15077 <para> 15078 None 15079 </para> 15080 </sect2> 15081 15082 <sect2 id="new-mail-credits"> 15083 <title>Credits</title> 15084 <para> 15085 Yoshiki Vazquez-Baeza, Santiago Torres-Arias, Richard Russon 15086 </para> 15087 </sect2> 15088 </sect1> 15089 15090 <sect1 id="nntp"> 15091 <title>NNTP Feature</title> 15092 <subtitle>Talk to a Usenet news server</subtitle> 15093 15094 <sect2 id="nntp-support"> 15095 <title>Support</title> 15096 <para> 15097 <emphasis role="bold">Since:</emphasis> NeoMutt 2016-05-30 15098 </para> 15099 <para> 15100 <emphasis role="bold">Dependencies:</emphasis> None 15101 </para> 15102 </sect2> 15103 15104 <sect2 id="nntp-intro"> 15105 <title>Introduction</title> 15106 <para> 15107 Reading news via NNTP 15108 </para> 15109 <para> 15110 NeoMutt can read from a news server using NNTP. 15111 </para> 15112 <para> 15113 The default news server can be obtained from the 15114 <literal>$NNTPSERVER</literal> environment variable or from the 15115 <literal>/etc/nntpserver</literal> file. Like in other news readers, 15116 information about the subscribed newsgroups is saved in the file 15117 specified by the <link linkend="newsrc">$newsrc</link> variable. You 15118 can open a newsgroup with the function 15119 <literal><change-newsgroup></literal> 15120 </para> 15121 <para> 15122 The variable <link linkend="news-cache-dir">$news_cache_dir</link> 15123 can be used to point to a directory. NeoMutt will create a hierarchy 15124 of subdirectories named like the account and newsgroup the cache is 15125 for. The hierarchy is also used to store header cache if NeoMutt was 15126 compiled with <link linkend="header-caching">header cache</link> 15127 support. 15128 </para> 15129 </sect2> 15130 15131 <sect2 id="nntp-variables"> 15132 <title>Variables</title> 15133 15134 <table id="table-nntp-variables"> 15135 <title>NNTP Variables</title> 15136 <tgroup cols="3"> 15137 <thead> 15138 <row> 15139 <entry>Name</entry> 15140 <entry>Type</entry> 15141 <entry>Default</entry> 15142 </row> 15143 </thead> 15144 <tbody> 15145 <row> 15146 <entry><literal>ask_follow_up</literal></entry> 15147 <entry>boolean</entry> 15148 <entry><literal>no</literal></entry> 15149 </row> 15150 <row> 15151 <entry><literal>ask_x_comment_to</literal></entry> 15152 <entry>boolean</entry> 15153 <entry><literal>no</literal></entry> 15154 </row> 15155 <row> 15156 <entry><literal>catchup_newsgroup</literal></entry> 15157 <entry>quad</entry> 15158 <entry><literal>ask-yes</literal></entry> 15159 </row> 15160 <row> 15161 <entry><literal>followup_to_poster</literal></entry> 15162 <entry>quad</entry> 15163 <entry><literal>ask-yes</literal></entry> 15164 </row> 15165 <row> 15166 <entry><literal>group_index_format</literal></entry> 15167 <entry>string</entry> 15168 <entry><literal>%4C %M%N %5s %-45.45f %d</literal></entry> 15169 </row> 15170 <row> 15171 <entry><literal>inews</literal></entry> 15172 <entry>string</entry> 15173 <entry>(empty)</entry> 15174 </row> 15175 <row> 15176 <entry><literal>newsgroups_charset</literal></entry> 15177 <entry>string</entry> 15178 <entry><literal>utf-8</literal></entry> 15179 </row> 15180 <row> 15181 <entry><literal>newsrc</literal></entry> 15182 <entry>string</entry> 15183 <entry><literal>~/.newsrc</literal></entry> 15184 </row> 15185 <row> 15186 <entry><literal>news_cache_dir</literal></entry> 15187 <entry>string</entry> 15188 <entry><literal>~/.neomutt</literal></entry> 15189 </row> 15190 <row> 15191 <entry><literal>news_server</literal></entry> 15192 <entry>string</entry> 15193 <entry>(empty)</entry> 15194 </row> 15195 <row> 15196 <entry><literal>nntp_authenticators</literal></entry> 15197 <entry>string</entry> 15198 <entry>(empty)</entry> 15199 </row> 15200 <row> 15201 <entry><literal>nntp_context</literal></entry> 15202 <entry>number</entry> 15203 <entry><literal>1000</literal></entry> 15204 </row> 15205 <row> 15206 <entry><literal>nntp_listgroup</literal></entry> 15207 <entry>boolean</entry> 15208 <entry><literal>yes</literal></entry> 15209 </row> 15210 <row> 15211 <entry><literal>nntp_load_description</literal></entry> 15212 <entry>boolean</entry> 15213 <entry><literal>yes</literal></entry> 15214 </row> 15215 <row> 15216 <entry><literal>nntp_pass</literal></entry> 15217 <entry>string</entry> 15218 <entry>(empty)</entry> 15219 </row> 15220 <row> 15221 <entry><literal>nntp_poll</literal></entry> 15222 <entry>number</entry> 15223 <entry><literal>60</literal></entry> 15224 </row> 15225 <row> 15226 <entry><literal>nntp_user</literal></entry> 15227 <entry>string</entry> 15228 <entry>(empty)</entry> 15229 </row> 15230 <row> 15231 <entry><literal>post_moderated</literal></entry> 15232 <entry>quad</entry> 15233 <entry><literal>ask-yes</literal></entry> 15234 </row> 15235 <row> 15236 <entry><literal>save_unsubscribed</literal></entry> 15237 <entry>boolean</entry> 15238 <entry><literal>no</literal></entry> 15239 </row> 15240 <row> 15241 <entry><literal>show_new_news</literal></entry> 15242 <entry>boolean</entry> 15243 <entry><literal>yes</literal></entry> 15244 </row> 15245 <row> 15246 <entry><literal>show_only_unread</literal></entry> 15247 <entry>boolean</entry> 15248 <entry><literal>no</literal></entry> 15249 </row> 15250 <row> 15251 <entry><literal>x_comment_to</literal></entry> 15252 <entry>boolean</entry> 15253 <entry><literal>no</literal></entry> 15254 </row> 15255 </tbody> 15256 </tgroup> 15257 </table> 15258 </sect2> 15259 15260 <sect2 id="nntp-functions"> 15261 <title>Functions</title> 15262 <para> 15263 NNTP adds the following functions to NeoMutt. By default, none of 15264 them are bound to keys. 15265 </para> 15266 15267 <table id="table-nntp-functions"> 15268 <title>NNTP Functions</title> 15269 <tgroup cols="3"> 15270 <thead> 15271 <row> 15272 <entry>Menus</entry> 15273 <entry>Function</entry> 15274 <entry>Description</entry> 15275 </row> 15276 </thead> 15277 <tbody> 15278 <row> 15279 <entry>browser,index</entry> 15280 <entry><literal><catchup></literal></entry> 15281 <entry>mark all articles in newsgroup as read</entry> 15282 </row> 15283 <row> 15284 <entry>index,pager</entry> 15285 <entry><literal><change-newsgroup></literal></entry> 15286 <entry>open a different newsgroup</entry> 15287 </row> 15288 <row> 15289 <entry>compose</entry> 15290 <entry><literal><edit-followup-to></literal></entry> 15291 <entry>edit the Followup-To field</entry> 15292 </row> 15293 <row> 15294 <entry>compose</entry> 15295 <entry><literal><edit-newsgroups></literal></entry> 15296 <entry>edit the newsgroups list</entry> 15297 </row> 15298 <row> 15299 <entry>compose</entry> 15300 <entry><literal><edit-x-comment-to></literal></entry> 15301 <entry>edit the X-Comment-To field</entry> 15302 </row> 15303 <row> 15304 <entry>attach,index,pager</entry> 15305 <entry><literal><followup-message></literal></entry> 15306 <entry>followup to newsgroup</entry> 15307 </row> 15308 <row> 15309 <entry>index,pager</entry> 15310 <entry><literal><post-message></literal></entry> 15311 <entry>post message to newsgroup</entry> 15312 </row> 15313 <row> 15314 <entry>browser</entry> 15315 <entry><literal><reload-active></literal></entry> 15316 <entry>load list of all newsgroups from NNTP server</entry> 15317 </row> 15318 <row> 15319 <entry>browser</entry> 15320 <entry><literal><subscribe></literal></entry> 15321 <entry>subscribe to current mbox (IMAP/NNTP only)</entry> 15322 </row> 15323 <row> 15324 <entry>browser</entry> 15325 <entry><literal><subscribe-pattern></literal></entry> 15326 <entry>subscribe to newsgroups matching a pattern</entry> 15327 </row> 15328 <row> 15329 <entry>browser</entry> 15330 <entry><literal><uncatchup></literal></entry> 15331 <entry>mark all articles in newsgroup as unread</entry> 15332 </row> 15333 <row> 15334 <entry>browser</entry> 15335 <entry><literal><unsubscribe></literal></entry> 15336 <entry>unsubscribe from current mbox (IMAP/NNTP only)</entry> 15337 </row> 15338 <row> 15339 <entry>browser</entry> 15340 <entry><literal><unsubscribe-pattern></literal></entry> 15341 <entry>unsubscribe from newsgroups matching a pattern</entry> 15342 </row> 15343 <row> 15344 <entry>index,pager</entry> 15345 <entry><literal><change-newsgroup-readonly></literal></entry> 15346 <entry>open a different newsgroup in read only mode</entry> 15347 </row> 15348 <row> 15349 <entry>attach,index,pager</entry> 15350 <entry><literal><forward-to-group></literal></entry> 15351 <entry>forward to newsgroup</entry> 15352 </row> 15353 <row> 15354 <entry>index</entry> 15355 <entry><literal><get-children></literal></entry> 15356 <entry>get all children of the current message</entry> 15357 </row> 15358 <row> 15359 <entry>index</entry> 15360 <entry><literal><get-parent></literal></entry> 15361 <entry>get parent of the current message</entry> 15362 </row> 15363 <row> 15364 <entry>index</entry> 15365 <entry><literal><reconstruct-thread></literal></entry> 15366 <entry>reconstruct thread containing current message</entry> 15367 </row> 15368 <row> 15369 <entry>index</entry> 15370 <entry><literal><get-message></literal></entry> 15371 <entry>get message with Message-Id</entry> 15372 </row> 15373 </tbody> 15374 </tgroup> 15375 </table> 15376 </sect2> 15377 15378 <sect2 id="nntp-neomuttrc"> 15379 <title>neomuttrc</title> 15380 15381<screen> 15382<emphasis role="comment"># Example NeoMutt config file for the nntp feature.</emphasis> 15383 15384<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 15385<emphasis role="comment"># VARIABLES – shown with their default values</emphasis> 15386<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 15387set ask_follow_up = no 15388set ask_x_comment_to = no 15389set catchup_newsgroup = ask-yes 15390set followup_to_poster = ask-yes 15391set group_index_format = '%4C %M%N %5s %-45.45f %d' 15392set inews = '' 15393set newsgroups_charset = utf-8 15394set newsrc = '~/.newsrc' 15395set news_cache_dir = '~/.neomutt' 15396set news_server = '' 15397set nntp_authenticators = '' 15398set nntp_context = 1000 15399set nntp_listgroup = yes 15400set nntp_load_description = yes 15401set nntp_pass = '' 15402set nntp_poll = 60 15403set nntp_user = '' 15404set post_moderated = ask-yes 15405set save_unsubscribed = no 15406set show_new_news = yes 15407set show_only_unread = no 15408set x_comment_to = no 15409<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 15410<emphasis role="comment"># FUNCTIONS – shown with an example mapping</emphasis> 15411<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 15412<emphasis role="comment"># mark all articles in newsgroup as read</emphasis> 15413bind browser,index y catchup 15414<emphasis role="comment"># open a different newsgroup</emphasis> 15415bind index,pager i change-newsgroup 15416<emphasis role="comment"># edit the Followup-To field</emphasis> 15417bind compose o edit-followup-to 15418<emphasis role="comment"># edit the newsgroups list</emphasis> 15419bind compose N edit-newsgroups 15420<emphasis role="comment"># edit the X-Comment-To field</emphasis> 15421bind compose x edit-x-comment-to 15422<emphasis role="comment"># followup to newsgroup</emphasis> 15423bind attach,index,pager F followup-message 15424<emphasis role="comment"># post message to newsgroup</emphasis> 15425bind index,pager P post-message 15426<emphasis role="comment"># load list of all newsgroups from NNTP server</emphasis> 15427bind browser g reload-active 15428<emphasis role="comment"># subscribe to current mbox (IMAP/NNTP only)</emphasis> 15429bind browser s subscribe 15430<emphasis role="comment"># subscribe to newsgroups matching a pattern</emphasis> 15431bind browser S subscribe-pattern 15432<emphasis role="comment"># mark all articles in newsgroup as unread</emphasis> 15433bind browser Y uncatchup 15434<emphasis role="comment"># unsubscribe from current mbox (IMAP/NNTP only)</emphasis> 15435bind browser u unsubscribe 15436<emphasis role="comment"># unsubscribe from newsgroups matching a pattern</emphasis> 15437bind browser U unsubscribe-pattern 15438<emphasis role="comment"># open a different newsgroup in read only mode</emphasis> 15439bind index,pager \ei change-newsgroup-readonly 15440<emphasis role="comment"># forward to newsgroup</emphasis> 15441bind attach,index,pager \eF forward-to-group 15442<emphasis role="comment"># get all children of the current message</emphasis> 15443<emphasis role="comment"># bind index ??? get-children</emphasis> 15444<emphasis role="comment"># get parent of the current message</emphasis> 15445bind index \eG get-parent 15446<emphasis role="comment"># reconstruct thread containing current message</emphasis> 15447<emphasis role="comment"># bind index ??? reconstruct-thread</emphasis> 15448<emphasis role="comment"># get message with Message-Id</emphasis> 15449bind index \CG get-message 15450<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 15451 15452<emphasis role="comment"># vim: syntax=neomuttrc</emphasis> 15453</screen> 15454 15455 </sect2> 15456 15457 <sect2 id="nntp-known-bugs"> 15458 <title>Known Bugs</title> 15459 <para> 15460 None 15461 </para> 15462 </sect2> 15463 15464 <sect2 id="nntp-credits"> 15465 <title>Credits</title> 15466 <para> 15467 Vsevolod Volkov, Felix von Leitner, Richard Russon 15468 </para> 15469 </sect2> 15470 </sect1> 15471 15472 <sect1 id="custom-tags"> 15473 <title>Custom backend based Tags Feature</title> 15474 <subtitle>Implements Notmuch tags and Imap keywords</subtitle> 15475 15476 <sect2 id="custom-tags-support"> 15477 <title>Support</title> 15478 <para> 15479 <emphasis role="bold">Since:</emphasis> NeoMutt 2017-10-16 15480 </para> 15481 <para> 15482 <emphasis role="bold">Dependencies:</emphasis> 15483 </para> 15484 <itemizedlist> 15485 <listitem> 15486 <para> 15487 <link linkend="quasi-delete">quasi-delete feature</link> 15488 </para> 15489 </listitem> 15490 <listitem> 15491 <para> 15492 <link linkend="index-color">index-color feature</link> 15493 </para> 15494 </listitem> 15495 </itemizedlist> 15496 </sect2> 15497 15498 <sect2 id="custom-tags-intro"> 15499 <title>Introduction</title> 15500 <para> 15501 Some backends allow to index and tags mail without storing the tags 15502 within the mail envelope. Two backends are currently implementing 15503 this feature. Notmuch handles them natively and IMAP stores them in 15504 custom IMAP keywords. 15505 </para> 15506 </sect2> 15507 15508 <sect2 id="custom-tags-variables"> 15509 <title>Variables</title> 15510 15511 <table id="table-custom-tags-variables"> 15512 <title>Custom tags Variables</title> 15513 <tgroup cols="3"> 15514 <thead> 15515 <row> 15516 <entry>Name</entry> 15517 <entry>Type</entry> 15518 <entry>Default</entry> 15519 </row> 15520 </thead> 15521 <tbody> 15522 <row> 15523 <entry><literal>hidden_tags</literal></entry> 15524 <entry>string</entry> 15525 <entry> 15526 <literal>unread,draft,flagged,passed,replied,attachment,signed,encrypted</literal> 15527 </entry> 15528 </row> 15529 </tbody> 15530 </tgroup> 15531 </table> 15532 </sect2> 15533 15534 <sect2 id="custom-tags-functions"> 15535 <title>Functions</title> 15536 <para> 15537 Notmuch adds the following functions to NeoMutt. By default, none of 15538 them are bound to keys. 15539 </para> 15540 15541 <table id="table-custom-tags-functions"> 15542 <title>Notmuch/IMAP Functions</title> 15543 <tgroup cols="3"> 15544 <thead> 15545 <row> 15546 <entry>Menus</entry> 15547 <entry>Function</entry> 15548 <entry>Description</entry> 15549 </row> 15550 </thead> 15551 <tbody> 15552 <row> 15553 <entry>index,pager</entry> 15554 <entry><literal><modify-labels></literal></entry> 15555 <entry> 15556 add, remove, or toggle tags: IMAP: edit the tags list 15557 Notmuch: [+]<tag> to add, -<tag> to remove, 15558 !<tag> to toggle(notmuch) tags. Note: Tab completion 15559 of tag names is available 15560 </entry> 15561 </row> 15562 <row> 15563 <entry>index,pager</entry> 15564 <entry><literal><modify-labels-then-hide></literal></entry> 15565 <entry> 15566 add, remove, or toggle tags IMAP: edit the tags list Notmuch: 15567 [+]<tag> to add, -<tag> to remove, !<tag> 15568 to toggle labels and then hide or unhide the message by 15569 changing the "quasi-deleted" to match if it would be shown 15570 when requerying. Normal redisplay rules apply here, so the 15571 user must call <sync-mailbox> for the changes to be 15572 displayed. Note: Tab completion of tag names is available. 15573 </entry> 15574 </row> 15575 </tbody> 15576 </tgroup> 15577 </table> 15578 </sect2> 15579 15580 <sect2 id="custom-tags-commands"> 15581 <title>Commands</title> 15582 <cmdsynopsis> 15583 <command>tag-transforms</command> 15584 <arg choice="plain"> 15585 <replaceable class="parameter">tag</replaceable> 15586 <arg choice="plain"> 15587 <replaceable class="parameter">transformed-string</replaceable> 15588 </arg> 15589 </arg> 15590 <group choice="req" rep="repeat"> 15591 <arg choice="plain"> 15592 <replaceable class="parameter">tag</replaceable> 15593 <arg choice="plain"> 15594 <replaceable class="parameter">transformed-string</replaceable> 15595 </arg> 15596 </arg> 15597 </group> 15598 <command>tag-formats</command> 15599 <arg choice="plain"> 15600 <replaceable class="parameter">tag</replaceable> 15601 <arg choice="plain"> 15602 <replaceable class="parameter">format-string</replaceable> 15603 </arg> 15604 </arg> 15605 <group choice="req" rep="repeat"> 15606 <arg choice="plain"> 15607 <replaceable class="parameter">tag</replaceable> 15608 <arg choice="plain"> 15609 <replaceable class="parameter">format-string</replaceable> 15610 </arg> 15611 </arg> 15612 </group> 15613 </cmdsynopsis> 15614 </sect2> 15615 15616 <sect2 id="custom-tags-colors"> 15617 <title>Colors</title> 15618 <para> 15619 Adds these to index-color feature: 15620 </para> 15621 15622 <table id="table-custom-tags-colors"> 15623 <title>Index Colors</title> 15624 <tgroup cols="3"> 15625 <thead> 15626 <row> 15627 <entry>Object</entry> 15628 <entry>Pattern</entry> 15629 <entry>Highlights</entry> 15630 </row> 15631 </thead> 15632 <tbody> 15633 <row> 15634 <entry><literal>index_tag</literal></entry> 15635 <entry>yes</entry> 15636 <entry>an individual message tag, %G, uses tag name</entry> 15637 </row> 15638 <row> 15639 <entry><literal>index_tags</literal></entry> 15640 <entry>no</entry> 15641 <entry>the transformed message tags, %g or %J</entry> 15642 </row> 15643 </tbody> 15644 </tgroup> 15645 </table> 15646 </sect2> 15647 15648 <sect2 id="custom-tags-neomuttrc"> 15649 <title>neomuttrc</title> 15650 15651<screen> 15652<emphasis role="comment"># Example NeoMutt config file for the custom tags feature.</emphasis> 15653 15654<emphasis role="comment"># VARIABLES – shown with their default values</emphasis> 15655<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 15656<emphasis role="comment"># This variable specifies private notmuch tags which should not be printed</emphasis> 15657<emphasis role="comment"># on screen (index, pager).</emphasis> 15658set hidden_tags = "unread,draft,flagged,passed,replied,attachment,signed,encrypted" 15659<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 15660<emphasis role="comment"># FUNCTIONS – shown with an example mapping</emphasis> 15661<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 15662<emphasis role="comment"># modify (notmuch/imap) tags</emphasis> 15663bind index,pager \` modify-labels 15664<emphasis role="comment"># modify (notmuch/imap) tag non-interactively.</emphasis> 15665macro index,pager tt "<modify-labels>!todo\n" "Toggle the 'todo' tag" 15666<emphasis role="comment"># modify labels and then hide message</emphasis> 15667<emphasis role="comment"># bind index,pager ??? modify-labels-then-hide</emphasis> 15668<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 15669<emphasis role="comment"># COMMANDS – shown with an example</emphasis> 15670<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 15671<emphasis role="comment"># Replace some tags with icons</emphasis> 15672<emphasis role="comment"># tag-transforms tag transformed-string { tag transformed-string ...}</emphasis> 15673<emphasis role="comment"># tag-transforms "inbox" "i" \</emphasis> 15674<emphasis role="comment"># "unread" "u" \</emphasis> 15675<emphasis role="comment"># "replied" "↻ " \</emphasis> 15676<emphasis role="comment"># "sent" "➥ " \</emphasis> 15677<emphasis role="comment"># "todo" "T" \</emphasis> 15678<emphasis role="comment"># "deleted" "DEL" \</emphasis> 15679<emphasis role="comment"># "invites" "CAL"</emphasis> 15680 15681<emphasis role="comment"># The formats must start with 'G' and the entire sequence is case sensitive.</emphasis> 15682<emphasis role="comment"># tag-formats tag format-string { tag format-string ...}</emphasis> 15683<emphasis role="comment"># tag-formats "inbox" "GI" \</emphasis> 15684<emphasis role="comment"># "unread" "GU" \</emphasis> 15685<emphasis role="comment"># "replied" "GR" \</emphasis> 15686<emphasis role="comment"># "sent" "GS" \</emphasis> 15687<emphasis role="comment"># "todo" "Gt" \</emphasis> 15688<emphasis role="comment"># "deleted" "GD" \</emphasis> 15689<emphasis role="comment"># "invites" "Gi"</emphasis> 15690 15691<emphasis role="comment"># Now instead of using '%g' or '%J' in your $index_format, which lists all tags</emphasis> 15692<emphasis role="comment"># in a non-deterministic order, you can something like the following which puts</emphasis> 15693<emphasis role="comment"># a transformed tag name in a specific spot on the index line:</emphasis> 15694<emphasis role="comment"># set index_format='%4C %S %[%y.%m.%d] %-18.18n %?GU?%GU& ? %?GR?%GR& ? %?GI?%GI& ? %s'</emphasis> 15695 15696<emphasis role="comment"># The %G formatting sequence may display all tags including tags hidden by</emphasis> 15697<emphasis role="comment"># hidden_tags.</emphasis> 15698<emphasis role="comment">#</emphasis> 15699<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 15700<emphasis role="comment"># COLORS – some unpleasant examples are given</emphasis> 15701<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 15702<emphasis role="comment"># These symbols are added to the index-color feature:</emphasis> 15703<emphasis role="comment"># an individual message tag, %G, uses tag name</emphasis> 15704<emphasis role="comment"># this symbol uses a pattern</emphasis> 15705color index_tag red white "inbox" 15706<emphasis role="comment"># the transformed message tags, %g</emphasis> 15707<emphasis role="comment"># this symbol does not use a pattern</emphasis> 15708color index_tags green default 15709<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 15710 15711<emphasis role="comment"># vim: syntax=neomuttrc</emphasis> 15712</screen> 15713 15714 </sect2> 15715 <sect2 id="custom-tags-credits"> 15716 <title>Credits</title> 15717 <para> 15718 Mehdi Abaakouk, Richard Russon, Bernard 'Guyzmo' Pratz 15719 </para> 15720 </sect2> 15721 </sect1> 15722 15723 <sect1 id="notmuch"> 15724 <title>Notmuch Feature</title> 15725 <subtitle>Email search engine</subtitle> 15726 15727 <sect2 id="notmuch-support"> 15728 <title>Support</title> 15729 <para> 15730 <emphasis role="bold">Since:</emphasis> NeoMutt 2016-03-17 15731 </para> 15732 <para> 15733 <emphasis role="bold">Dependencies:</emphasis> 15734 </para> 15735 <itemizedlist> 15736 <listitem> 15737 <para> 15738 <link linkend="quasi-delete">quasi-delete feature</link> 15739 </para> 15740 </listitem> 15741 <listitem> 15742 <para> 15743 <link linkend="index-color">index-color feature</link> 15744 </para> 15745 </listitem> 15746 <listitem> 15747 <para> 15748 Notmuch libraries 15749 </para> 15750 </listitem> 15751 </itemizedlist> 15752 </sect2> 15753 15754 <sect2 id="notmuch-intro"> 15755 <title>Introduction</title> 15756 <para> 15757 Notmuch is an email fulltext indexing and tagging engine. 15758 </para> 15759 <itemizedlist> 15760 <listitem> 15761 <para> 15762 For more information, see: 15763 <ulink url="https://notmuchmail.org">https://notmuchmail.org/</ulink> 15764 </para> 15765 </listitem> 15766 <listitem> 15767 <para> 15768 More examples: 15769 <ulink url="https://notmuchmail.org/mutttips/">https://notmuchmail.org/mutttips/</ulink> 15770 </para> 15771 </listitem> 15772 </itemizedlist> 15773 </sect2> 15774 15775 <sect2 id="notmuch-using"> 15776 <title>Using Notmuch</title> 15777 15778 <sect3 id="notmuch-folder-url"> 15779 <title>Folders URL</title> 15780 <para> 15781 <emphasis role="bold">notmuch://[<path>][?<item>=<name>[& ...]]</emphasis> 15782 </para> 15783 <para> 15784 The <path> is an absolute path to the directory where the 15785 notmuch database is found as returned by 15786 <quote>notmuch config get database.path</quote> command. Note that 15787 the <path> should NOT include <literal>.notmuch</literal> 15788 directory name. 15789 </para> 15790 <para> 15791 If the "<path>" is not defined then 15792 <literal>$nm_default_url</literal> or <literal>$folder</literal> is 15793 used, for example: 15794 </para> 15795 15796<screen> 15797set nm_default_url = "notmuch:///home/foo/maildir" 15798virtual-mailboxes "My INBOX" "notmuch://?query=tag:inbox" 15799</screen> 15800 15801 </sect3> 15802 15803 <sect3 id="notmuch-items"> 15804 <title>Items</title> 15805 <para> 15806 <emphasis role="bold">query=<string></emphasis> 15807 </para> 15808 <para> 15809 See SEARCH SYNTAX in notmuch man page. Don't forget to use 15810 operators (<quote>and</quote>/<quote>or</quote>) in your queries. 15811 </para> 15812 <para> 15813 Note that proper URL should not contain blank space and all 15814 <quote>bad</quote> chars should be encoded, for example 15815 </para> 15816 <para> 15817 <literal>tag:AAA and tag:BBB</literal> – encoding -> 15818 <literal>tag:AAA%20and%20tag:BBB</literal> 15819 </para> 15820 <para> 15821 but NeoMutt config file parser is smart enough to accept space in 15822 quoted strings. It means that you can use 15823 </para> 15824 <para> 15825 <literal>notmuch:///foo?query=tag:AAA and tag:BBB</literal> 15826 </para> 15827 <para> 15828 in your config files to keep things readable. 15829 </para> 15830 <para> 15831 For more details about Xapian queries, see: 15832 <ulink url="https://xapian.org/docs/queryparser.html">https://xapian.org/docs/queryparser.html</ulink> 15833 </para> 15834 <para> 15835 <emphasis role="bold">limit=<number></emphasis> 15836 </para> 15837 <para> 15838 Restricts number of messages/threads in the result. The default 15839 limit is nm_db_limit. 15840 </para> 15841 <para> 15842 Due to a limitation with <literal>libnotmuch</literal>, unread and 15843 flagged message count may be inaccurate with limit statements. 15844 <literal>libnotmuch</literal> cannot return a specific tag count 15845 within the first X messages of a query. 15846 </para> 15847 <para> 15848 <emphasis role="bold">type=<threads|messages></emphasis> 15849 </para> 15850 <para> 15851 Reads all matching messages or whole-threads. The default is 15852 'messages' or nm_query_type. 15853 </para> 15854 </sect3> 15855 15856 <sect3 id="notmuch-vfolder-format"> 15857 <title>Format String for the Notmuch Browser</title> 15858 <para> 15859 Default: 15860 <literallayout> 15861 <literal>%2C %?n?%4n/& ?%4m %f</literal> 15862 </literallayout> 15863 </para> 15864 <para> 15865 This variable allows you to customize the browser display to your 15866 personal taste. This string is similar to 15867 <link linkend="index-format">$index_format</link>, but has its own 15868 set of <literal>printf(3)</literal>-like sequences: 15869 </para> 15870 <informaltable> 15871 <tgroup cols="2"> 15872 <tbody> 15873 <row> 15874 <entry>%C</entry> 15875 <entry> 15876 current file number 15877 </entry> 15878 </row> 15879 <row> 15880 <entry>%f</entry> 15881 <entry> 15882 folder name (description) 15883 </entry> 15884 </row> 15885 <row> 15886 <entry>%m</entry> 15887 <entry> 15888 number of messages in the mailbox * 15889 </entry> 15890 </row> 15891 <row> 15892 <entry>%n</entry> 15893 <entry> 15894 number of unread messages in the mailbox * 15895 </entry> 15896 </row> 15897 <row> 15898 <entry>%N</entry> 15899 <entry> 15900 N if mailbox has new mail, blank otherwise 15901 </entry> 15902 </row> 15903 <row> 15904 <entry>%>X</entry> 15905 <entry> 15906 right justify the rest of the string and pad with character 15907 <quote>X</quote> 15908 </entry> 15909 </row> 15910 <row> 15911 <entry>%|X</entry> 15912 <entry> 15913 pad to the end of the line with character <quote>X</quote> 15914 </entry> 15915 </row> 15916 <row> 15917 <entry>%*X</entry> 15918 <entry> 15919 soft-fill with character <quote>X</quote> as pad 15920 </entry> 15921 </row> 15922 </tbody> 15923 </tgroup> 15924 </informaltable> 15925 <para> 15926 For an explanation of <quote>soft-fill</quote>, see the 15927 <link linkend="index-format">$index_format</link> documentation. 15928 </para> 15929 <para> 15930 * = can be optionally printed if nonzero 15931 </para> 15932 </sect3> 15933 </sect2> 15934 15935 <sect2 id="notmuch-variables"> 15936 <title>Variables</title> 15937 15938 <table id="table-notmuch-variables"> 15939 <title>Notmuch Variables</title> 15940 <tgroup cols="4"> 15941 <thead> 15942 <row> 15943 <entry>Name</entry> 15944 <entry>Type</entry> 15945 <entry>Default</entry> 15946 <entry>Note</entry> 15947 </row> 15948 </thead> 15949 <tbody> 15950 <row> 15951 <entry><literal>nm_db_limit</literal></entry> 15952 <entry>number</entry> 15953 <entry><literal>0</literal></entry> 15954 <entry></entry> 15955 </row> 15956 <row> 15957 <entry><literal>nm_default_url</literal></entry> 15958 <entry>string</entry> 15959 <entry>(empty)</entry> 15960 <entry> 15961 Must use format: <literal>notmuch://<absolute path></literal> 15962 </entry> 15963 </row> 15964 <row> 15965 <entry><literal>nm_exclude_tags</literal></entry> 15966 <entry>string</entry> 15967 <entry>(empty)</entry> 15968 <entry></entry> 15969 </row> 15970 <row> 15971 <entry><literal>nm_open_timeout</literal></entry> 15972 <entry>number</entry> 15973 <entry><literal>5</literal></entry> 15974 <entry></entry> 15975 </row> 15976 <row> 15977 <entry><literal>nm_query_type</literal></entry> 15978 <entry>string</entry> 15979 <entry><literal>messages</literal></entry> 15980 <entry></entry> 15981 </row> 15982 <row> 15983 <entry><literal>nm_record</literal></entry> 15984 <entry>boolean</entry> 15985 <entry><literal>no</literal></entry> 15986 <entry></entry> 15987 </row> 15988 <row> 15989 <entry><literal>nm_record_tags</literal></entry> 15990 <entry>string</entry> 15991 <entry>(empty)</entry> 15992 <entry></entry> 15993 </row> 15994 <row> 15995 <entry><literal>nm_unread_tag</literal></entry> 15996 <entry>string</entry> 15997 <entry><literal>unread</literal></entry> 15998 <entry></entry> 15999 </row> 16000 <row> 16001 <entry><literal>vfolder_format</literal></entry> 16002 <entry>string</entry> 16003 <entry><literal>%6n(%6N) %f</literal></entry> 16004 <entry></entry> 16005 </row> 16006 <row> 16007 <entry><literal>virtual_spool_file</literal></entry> 16008 <entry>boolean</entry> 16009 <entry><literal>no</literal></entry> 16010 <entry> 16011 Unnecessary since <link linkend="spool-file">$spool_file</link> 16012 supports mailbox descriptions. 16013 </entry> 16014 </row> 16015 <row> 16016 <entry><literal>nm_query_window_enable</literal></entry> 16017 <entry>boolean</entry> 16018 <entry><literal>no</literal></entry> 16019 <entry> 16020 Enables windowed notmuch queries for 16021 <literal>nm_query_window_duration = 0</literal> 16022 </entry> 16023 </row> 16024 <row> 16025 <entry><literal>nm_query_window_duration</literal></entry> 16026 <entry>number</entry> 16027 <entry><literal>0</literal></entry> 16028 <entry> 16029 Duration between start and end dates for windowed notmuch query. 16030 This corresponds to a bounded notmuch <literal>date:</literal> query. 16031 See <literal>notmuch-search-terms</literal> manual page for more info. 16032 16033 Value of <literal>0</literal> disables windowed queries unless 16034 <literal>nm_query_window_enable=yes</literal> 16035 </entry> 16036 </row> 16037 <row> 16038 <entry><literal>nm_query_window_or_terms</literal></entry> 16039 <entry>string</entry> 16040 <entry><literal>(empty)</literal></entry> 16041 <entry> 16042 Additional notmuch search terms to always include in the 16043 window even if they're outside the date range. This turns the 16044 window from <literal>date:...</literal> to 16045 <literal>date:... or (additional search terms.)</literal> 16046 16047 For example, to always include flagged, unread emails, set to 16048 <literal>tag:flagged and tag:unread</literal> 16049 </entry> 16050 </row> 16051 <row> 16052 <entry><literal>nm_query_window_timebase</literal></entry> 16053 <entry>string</entry> 16054 <entry><literal>week</literal></entry> 16055 <entry> 16056 Time base for windowed notmuch queries. 16057 16058 Must be one of: <literal>hour</literal>, <literal>day</literal>, 16059 <literal>week</literal>, <literal>month</literal>, or 16060 <literal>year</literal> 16061 </entry> 16062 </row> 16063 </tbody> 16064 </tgroup> 16065 </table> 16066 <para> 16067 More variables about tags configuration can be found in 16068 <link linkend="custom-tags-variables">Custom backend Tags Feature</link> 16069 </para> 16070 </sect2> 16071 16072 <sect2 id="notmuch-functions"> 16073 <title>Functions</title> 16074 <para> 16075 Notmuch adds the following functions to NeoMutt. By default, none of 16076 them are bound to keys. 16077 </para> 16078 16079 <table id="table-notmuch-functions"> 16080 <title>Notmuch Functions</title> 16081 <tgroup cols="3"> 16082 <thead> 16083 <row> 16084 <entry>Menus</entry> 16085 <entry>Function</entry> 16086 <entry>Description</entry> 16087 </row> 16088 </thead> 16089 <tbody> 16090 <row> 16091 <entry>index,pager</entry> 16092 <entry><literal><change-vfolder></literal></entry> 16093 <entry> 16094 switch to another virtual folder, a new folder maybe be 16095 specified by vfolder description (see virtual-mailboxes) or 16096 URL. the default is next vfolder with unread messages 16097 </entry> 16098 </row> 16099 <row> 16100 <entry>index,pager</entry> 16101 <entry><literal><entire-thread></literal></entry> 16102 <entry> 16103 read entire thread of the current message 16104 </entry> 16105 </row> 16106 <row> 16107 <entry>index,pager</entry> 16108 <entry><literal><sidebar-toggle-virtual></literal></entry> 16109 <entry> 16110 toggle between mailboxes and virtual mailboxes 16111 </entry> 16112 </row> 16113 <row> 16114 <entry>index,pager</entry> 16115 <entry><literal><vfolder-from-query></literal></entry> 16116 <entry> 16117 generate virtual folder from notmuch search query. Note: TAB 16118 completion of 'tag:' names is available. 16119 </entry> 16120 </row> 16121 <row> 16122 <entry>index,pager</entry> 16123 <entry><literal><vfolder-from-query-readonly></literal></entry> 16124 <entry> 16125 The same as <literal><vfolder-from-query></literal>; however, the mailbox 16126 will be read-only. 16127 </entry> 16128 </row> 16129 <row> 16130 <entry>index</entry> 16131 <entry><literal><vfolder-window-forward></literal></entry> 16132 <entry> 16133 generate virtual folder by moving the query's time window 16134 forward 16135 </entry> 16136 </row> 16137 <row> 16138 <entry>index</entry> 16139 <entry><literal><vfolder-window-backward></literal></entry> 16140 <entry> 16141 generate virtual folder by moving the query's time window 16142 backward 16143 </entry> 16144 </row> 16145 <row> 16146 <entry>index</entry> 16147 <entry><literal><vfolder-window-reset></literal></entry> 16148 <entry> 16149 generate virtual folder by moving the query's time window to 16150 the present 16151 </entry> 16152 </row> 16153 </tbody> 16154 </tgroup> 16155 </table> 16156 <para> 16157 More functions about tags can be found in 16158 <link linkend="custom-tags-functions">Custom backend Tags Feature</link> 16159 </para> 16160 </sect2> 16161 16162 <sect2 id="notmuch-commands"> 16163 <title>Commands</title> 16164 <cmdsynopsis> 16165 <command>virtual-mailboxes</command> 16166 <arg choice="plain"> 16167 <replaceable class="parameter">description</replaceable> 16168 <arg choice="plain"> 16169 <replaceable class="parameter">notmuch-URL</replaceable> 16170 </arg> 16171 </arg> 16172 <group choice="req" rep="repeat"> 16173 <arg choice="plain"> 16174 <replaceable class="parameter">description</replaceable> 16175 <arg choice="plain"> 16176 <replaceable class="parameter">notmuch-URL</replaceable> 16177 </arg> 16178 </arg> 16179 </group> 16180 <command>unvirtual-mailboxes</command> 16181 <group choice="req"> 16182 <arg choice="plain"> 16183 <replaceable class="parameter">*</replaceable> 16184 </arg> 16185 <arg choice="plain" rep="repeat"> 16186 <replaceable class="parameter">mailbox</replaceable> 16187 </arg> 16188 </group> 16189 </cmdsynopsis> 16190 <para> 16191 <literal>virtual-mailboxes</literal> is like the 16192 <link linkend="mailboxes">mailboxes</link> command, except that it 16193 takes a description. The mailbox will be watched for new mail and 16194 will appear in the sidebar. 16195 </para> 16196 <para> 16197 <literal>unvirtual-mailboxes</literal> is identical to the 16198 <literal>unmailboxes</literal> command. 16199 </para> 16200 <para> 16201 More commands about tags can be found in 16202 <link linkend="custom-tags-commands">Custom backend Tags Feature</link> 16203 </para> 16204 </sect2> 16205 16206 <sect2 id="notmuch-colors"> 16207 <title>Colors</title> 16208 <para> 16209 See 16210 <link linkend="custom-tags-colors">Custom backend Tags colors</link> 16211 </para> 16212 </sect2> 16213 16214 <sect2 id="notmuch-neomuttrc"> 16215 <title>neomuttrc</title> 16216 16217<screen> 16218<emphasis role="comment"># Example NeoMutt config file for the notmuch feature.</emphasis> 16219 16220<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 16221<emphasis role="comment"># VARIABLES – shown with their default values</emphasis> 16222<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 16223<emphasis role="comment"># This variable specifies notmuch query limit.</emphasis> 16224set nm_db_limit = 0 16225<emphasis role="comment"># This variable specifies the default Notmuch database in format:</emphasis> 16226<emphasis role="comment"># notmuch://<absolute path></emphasis> 16227set nm_default_url = "" 16228<emphasis role="comment"># The messages tagged with these tags are excluded and not loaded</emphasis> 16229<emphasis role="comment"># from notmuch DB to NeoMutt unless specified explicitly.</emphasis> 16230set nm_exclude_tags = "" 16231<emphasis role="comment"># This option specifies timeout for Notmuch database. Default is 5 seconds.</emphasis> 16232set nm_open_timeout = 5 16233<emphasis role="comment"># This variable specifies notmuch query type, supported types: 'threads' and</emphasis> 16234<emphasis role="comment"># 'messages'.</emphasis> 16235set nm_query_type = messages 16236<emphasis role="comment"># Add messages stored to the NeoMutt record (see $record in the NeoMutt docs)</emphasis> 16237<emphasis role="comment"># also to notmuch DB. If you reply to an email then the new email inherits</emphasis> 16238<emphasis role="comment"># tags from the original email.</emphasis> 16239set nm_record = no 16240<emphasis role="comment"># Tags that should be removed or added to the to the messages stored in the NeoMutt record.</emphasis> 16241<emphasis role="comment"># example:</emphasis> 16242<emphasis role="comment"># set record = "~/sent-mails"</emphasis> 16243<emphasis role="comment"># set nm_record = yes</emphasis> 16244<emphasis role="comment"># set nm_record_tags = "-inbox,archive,me"</emphasis> 16245set nm_record_tags = "" 16246<emphasis role="comment"># This variable specifies notmuch tag which is used for unread messages.</emphasis> 16247set nm_unread_tag = unread 16248<emphasis role="comment"># This variable allows you to customize the file browser display for virtual</emphasis> 16249<emphasis role="comment"># folders to your personal taste.</emphasis> 16250<emphasis role="comment"># %C current folder number</emphasis> 16251<emphasis role="comment"># %f folder name (description)</emphasis> 16252<emphasis role="comment"># %m number of messages in the mailbox *</emphasis> 16253<emphasis role="comment"># %n number of unread messages in the mailbox *</emphasis> 16254<emphasis role="comment"># %N N if mailbox has new mail, blank otherwise</emphasis> 16255<emphasis role="comment"># %>X right justify the rest of the string and pad with character ``X''</emphasis> 16256<emphasis role="comment"># %|X pad to the end of the line with character ``X''</emphasis> 16257<emphasis role="comment"># %*X soft-fill with character ``X'' as pad</emphasis> 16258set vfolder_format = "%6n(%6N) %f" 16259<emphasis role="comment"># When set, NeoMutt will use the first virtual mailbox (see virtual-mailboxes)</emphasis> 16260<emphasis role="comment"># as a spool_file.</emphasis> 16261set virtual_spool_file = no 16262<emphasis role="comment"># setup time window preferences</emphasis> 16263<emphasis role="comment"># first setup the duration, and then the time unit of that duration</emphasis> 16264<emphasis role="comment"># when set to 0 (the default) the search window feature is disabled</emphasis> 16265<emphasis role="comment"># unless explicitly enabled with nm_query_window_enable.</emphasis> 16266set nm_query_window_enable=yes 16267set nm_query_window_duration=2 16268set nm_query_window_timebase="week" # or "hour", "day", "week", "month", "year" 16269<emphasis role="comment"># Extend query window to always show mail matching these terms.</emphasis> 16270set nm_query_window_or_terms="tag:unread and tag:flagged" 16271<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 16272<emphasis role="comment"># FUNCTIONS – shown with an example mapping</emphasis> 16273<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 16274<emphasis role="comment"># open a different virtual folder</emphasis> 16275bind index,pager X change-vfolder 16276<emphasis role="comment"># read entire thread of the current message</emphasis> 16277bind index,pager + entire-thread 16278<emphasis role="comment"># generate virtual folder from query</emphasis> 16279bind index,pager \eX vfolder-from-query 16280<emphasis role="comment"># generate virtual folder from query with time window</emphasis> 16281bind index < vfolder-window-backward 16282bind index > vfolder-window-forward 16283<emphasis role="comment"># toggle between mailboxes and virtual mailboxes</emphasis> 16284<emphasis role="comment"># bind index,pager ??? sidebar-toggle-virtual</emphasis> 16285<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 16286<emphasis role="comment"># COMMANDS – shown with an example</emphasis> 16287<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 16288<emphasis role="comment"># virtual-mailboxes description notmuch-URL { description notmuch-URL ...}</emphasis> 16289<emphasis role="comment"># virtual-mailboxes "Climbing" "notmuch://?query=climbing"</emphasis> 16290<emphasis role="comment"># unvirtual-mailboxes { * | mailbox ...}</emphasis> 16291<emphasis role="comment">#</emphasis> 16292<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 16293 16294<emphasis role="comment"># vim: syntax=neomuttrc</emphasis> 16295</screen> 16296 16297 </sect2> 16298 16299 <sect2 id="notmuch-see-also"> 16300 <title>See Also</title> 16301 <itemizedlist> 16302 <listitem> 16303 <para> 16304 <link linkend="compile-time-features">Compile-Time Features</link> 16305 </para> 16306 </listitem> 16307 </itemizedlist> 16308 </sect2> 16309 16310 <sect2 id="notmuch-known-bugs"> 16311 <title>Known Bugs</title> 16312 <para> 16313 None 16314 </para> 16315 </sect2> 16316 16317 <sect2 id="notmuch-credits"> 16318 <title>Credits</title> 16319 <para> 16320 Karel Zak, Chris Mason, Christoph Rissner, David Riebenbauer, 16321 David Sterba, David Wilson, Don Zickus, Eric Davis, Jan Synacek, 16322 Jeremiah C. Foster, Josh Poimboeuf, Kirill A. Shutemov, Luke Macken, 16323 Mantas Mikulėnas, Patrick Brisbin, Philippe Le Brouster, 16324 Raghavendra D Prabhu, Sami Farin, Stefan Assmann, Stefan Kuhn, 16325 Tim Stoakes, Vladimir Marek, Víctor Manuel Jáquez Leal, 16326 Richard Russon, Bernard 'Guyzmo' Pratz 16327 </para> 16328 </sect2> 16329 </sect1> 16330 16331 <sect1 id="pager-read-delay-feature"> 16332 <title>Pager Read Delay Feature</title> 16333 <subtitle>Delay when the pager marks a previewed message as 16334 read</subtitle> 16335 16336 <sect2 id="pager-read-delay-support"> 16337 <title>Support</title> 16338 <para> 16339 <emphasis role="bold">Since:</emphasis> NeoMutt 2021-06-16 16340 </para> 16341 <para> 16342 <emphasis role="bold">Dependencies:</emphasis> None 16343 </para> 16344 </sect2> 16345 16346 <sect2 id="pager-read-delay-intro"> 16347 <title>Introduction</title> 16348 <para> 16349 The <quote>Pager Read Delay</quote> feature adds a new 16350 config variable to allow the pager to operate in a preview 16351 mode. A new message is not marked as read merely because 16352 the pager opened it, but only after the pager remains on the 16353 message for a given length of time. 16354 </para> 16355 </sect2> 16356 16357 <sect2 id="pager-read-delay-functions"> 16358 <title>Functions</title> 16359 <para> 16360 The <quote>Pager Read Delay</quote> feature adds no new 16361 functions to NeoMutt. Existing pager functions for navigating 16362 to a different message now check whether to mark a message 16363 as read. 16364 </para> 16365 </sect2> 16366 16367 <sect2 id="pager-read-delay-variables"> 16368 <title>Variables</title> 16369 <para> 16370 The <quote>Pager Read Delay</quote> feature adds one new 16371 config variable, 16372 <link linkend="pager-read-delay">$pager_read_delay</link>, which 16373 is an integer for how many seconds the pager must remain on 16374 a given message before marking it as read. The variable 16375 defaults to 0 for the original behavior of marking a message 16376 as read the moment the pager visits it. 16377 </para> 16378 </sect2> 16379 16380 <sect2 id="pager-read-delay-neomuttrc"> 16381 <title>neomuttrc</title> 16382 16383<screen> 16384<emphasis role="comment"># Example NeoMutt config file for the pager-read-delay feature.</emphasis> 16385 16386<emphasis role="comment"># Stay at least 5 seconds on a message before the pager marks it as read</emphasis> 16387set pager_read_delay = 5 16388 16389<emphasis role="comment"># vim: syntax=neomuttrc</emphasis> 16390</screen> 16391 16392 </sect2> 16393 16394 <sect2 id="pager-read-delay-known-bugs"> 16395 <title>Known Bugs</title> 16396 <para> 16397 When <link linkend="pager-index-lines">$pager_index_lines</link> is 16398 non-zero, the <quote>N</quote> status indicator from the 16399 <quote>%Z</quote> expando of <link 16400 linkend="index-format">$index_format</link> does not 16401 actively reflect the current new/read status of the message. 16402 </para> 16403 </sect2> 16404 16405 <sect2 id="pager-read-delay-credits"> 16406 <title>Credits</title> 16407 <para> 16408 Eric Blake 16409 </para> 16410 </sect2> 16411 </sect1> 16412 16413 <sect1 id="progress"> 16414 <title>Progress Bar Feature</title> 16415 <subtitle>Show a visual progress bar on slow operations</subtitle> 16416 16417 <sect2 id="progress-support"> 16418 <title>Support</title> 16419 <para> 16420 <emphasis role="bold">Since:</emphasis> NeoMutt 2016-03-07 16421 </para> 16422 <para> 16423 <emphasis role="bold">Dependencies:</emphasis> None 16424 </para> 16425 </sect2> 16426 16427 <sect2 id="progress-intro"> 16428 <title>Introduction</title> 16429 <para> 16430 The <quote>progress</quote> feature shows a visual progress bar on 16431 slow tasks, such as indexing a large folder over the net. 16432 </para> 16433 </sect2> 16434 16435 <sect2 id="progress-colors"> 16436 <title>Colors</title> 16437 16438 <table id="table-progress-colors"> 16439 <title>Progress Colors</title> 16440 <tgroup cols="3"> 16441 <thead> 16442 <row> 16443 <entry>Name</entry> 16444 <entry>Default Color</entry> 16445 <entry>Description</entry> 16446 </row> 16447 </thead> 16448 <tbody> 16449 <row> 16450 <entry><literal>progress</literal></entry> 16451 <entry>default</entry> 16452 <entry>Visual progress bar</entry> 16453 </row> 16454 </tbody> 16455 </tgroup> 16456 </table> 16457 </sect2> 16458 16459 <sect2 id="progress-neomuttrc"> 16460 <title>neomuttrc</title> 16461 16462<screen> 16463<emphasis role="comment"># Example NeoMutt config file for the progress feature.</emphasis> 16464 16465<emphasis role="comment"># The 'progress' feature provides clear visual feedback for</emphasis> 16466<emphasis role="comment"># slow tasks, such as indexing a large folder over the net.</emphasis> 16467 16468<emphasis role="comment"># Set the color of the progress bar</emphasis> 16469<emphasis role="comment"># White text on a red background</emphasis> 16470color progress white red 16471 16472<emphasis role="comment"># vim: syntax=neomuttrc</emphasis> 16473</screen> 16474 16475 </sect2> 16476 16477 <sect2 id="progress-see-also"> 16478 <title>See Also</title> 16479 <itemizedlist> 16480 <listitem> 16481 <para> 16482 <link linkend="color">Color command</link> 16483 </para> 16484 </listitem> 16485 </itemizedlist> 16486 </sect2> 16487 16488 <sect2 id="progress-known-bugs"> 16489 <title>Known Bugs</title> 16490 <para> 16491 None 16492 </para> 16493 </sect2> 16494 16495 <sect2 id="progress-credits"> 16496 <title>Credits</title> 16497 <para> 16498 Rocco Rutte, Vincent Lefevre, Stefan Kuhn, Karel Zak, Richard Russon 16499 </para> 16500 </sect2> 16501 </sect1> 16502 16503 <sect1 id="quasi-delete"> 16504 <title>Quasi-Delete Feature</title> 16505 <subtitle>Mark emails that should be hidden, but not deleted</subtitle> 16506 16507 <sect2 id="quasi-delete-support"> 16508 <title>Support</title> 16509 <para> 16510 <emphasis role="bold">Since:</emphasis> NeoMutt 2016-03-07 16511 </para> 16512 <para> 16513 <emphasis role="bold">Dependencies:</emphasis> None 16514 </para> 16515 </sect2> 16516 16517 <sect2 id="quasi-delete-intro"> 16518 <title>Introduction</title> 16519 <para> 16520 The <quote>quasi-delete</quote> function marks an email that should 16521 be hidden from the index, but NOT deleted. The email will disappear 16522 from the index when 16523 <link linkend="index-map"><sync-mailbox></link> is called. 16524 </para> 16525 <para> 16526 On its own, this feature isn't very useful. It forms a useful part of 16527 the notmuch plugin. 16528 </para> 16529 </sect2> 16530 16531 <sect2 id="quasi-delete-functions"> 16532 <title>Functions</title> 16533 16534 <table id="table-quasi-delete-functions"> 16535 <title>Quasi-Delete Functions</title> 16536 <tgroup cols="4"> 16537 <thead> 16538 <row> 16539 <entry>Menus</entry> 16540 <entry>Default Key</entry> 16541 <entry>Function</entry> 16542 <entry>Description</entry> 16543 </row> 16544 </thead> 16545 <tbody> 16546 <row> 16547 <entry>index,pager</entry> 16548 <entry>(none)</entry> 16549 <entry><literal><quasi-delete></literal></entry> 16550 <entry>delete from NeoMutt, don't touch on disk</entry> 16551 </row> 16552 </tbody> 16553 </tgroup> 16554 </table> 16555 </sect2> 16556 16557 <sect2 id="quasi-delete-neomuttrc"> 16558 <title>neomuttrc</title> 16559 16560<screen> 16561<emphasis role="comment"># Example NeoMutt config file for the quasi-delete feature.</emphasis> 16562 16563<emphasis role="comment"># The 'quasi-delete' function marks an email that should be hidden</emphasis> 16564<emphasis role="comment"># from the index, but NOT deleted.</emphasis> 16565bind index,pager Q quasi-delete 16566 16567<emphasis role="comment"># vim: syntax=neomuttrc</emphasis> 16568</screen> 16569 16570 </sect2> 16571 16572 <sect2 id="quasi-delete-see-also"> 16573 <title>See Also</title> 16574 <itemizedlist> 16575 <listitem> 16576 <para> 16577 <link linkend="notmuch">notmuch feature</link> 16578 </para> 16579 </listitem> 16580 </itemizedlist> 16581 </sect2> 16582 16583 <sect2 id="quasi-delete-known-bugs"> 16584 <title>Known Bugs</title> 16585 <para> 16586 None 16587 </para> 16588 </sect2> 16589 16590 <sect2 id="quasi-delete-credits"> 16591 <title>Credits</title> 16592 <para> 16593 Karel Zak, Richard Russon 16594 </para> 16595 </sect2> 16596 </sect1> 16597 16598 <sect1 id="reply-with-xorig-patch"> 16599 <title>Reply With X-Original-To Feature</title> 16600 <subtitle>Direct reply to email using X-Original-To header</subtitle> 16601 16602 <sect2 id="reply-with-xorig-support"> 16603 <title>Support</title> 16604 <para> 16605 <emphasis role="bold">Since:</emphasis> NeoMutt 2016-09-10 16606 </para> 16607 <para> 16608 <emphasis role="bold">Dependencies:</emphasis> None 16609 </para> 16610 </sect2> 16611 16612 <sect2 id="reply-with-xorig-intro"> 16613 <title>Introduction</title> 16614 <para> 16615 Adds a reply_with_xorig for NeoMutt configuration files. If enabled, 16616 allows to reply to an email using the email address in the first 16617 X-Original-To: header of a mail as the From: header of the answer. 16618 </para> 16619 </sect2> 16620 16621 <sect2 id="reply-with-xorig-variables"> 16622 <title>Variables</title> 16623 16624 <table id="table-reply-with-xorig-variables"> 16625 <title>Reply With X-Original-To Variables</title> 16626 <tgroup cols="3"> 16627 <thead> 16628 <row> 16629 <entry>Name</entry> 16630 <entry>Type</entry> 16631 <entry>Default</entry> 16632 </row> 16633 </thead> 16634 <tbody> 16635 <row> 16636 <entry><literal>reply_with_xorig</literal></entry> 16637 <entry>Boolean</entry> 16638 <entry><literal>no</literal></entry> 16639 </row> 16640 </tbody> 16641 </tgroup> 16642 </table> 16643 </sect2> 16644 16645 <sect2 id="reply-with-xorig-neomuttrc"> 16646 <title>neomuttrc</title> 16647 16648<screen> 16649<emphasis role="comment"># Example NeoMutt config file for the reply-with-xorig feature.</emphasis> 16650 16651<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 16652<emphasis role="comment"># VARIABLES – shown with their default values</emphasis> 16653<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 16654<emphasis role="comment"># Use X-Original-To header to reply when reverse is disabled or no alternate</emphasis> 16655<emphasis role="comment"># is found.</emphasis> 16656set reply_with_xorig = "yes" 16657 16658<emphasis role="comment"># vim: syntax=neomuttrc</emphasis> 16659</screen> 16660 16661 </sect2> 16662 16663 <sect2 id="reply-with-xorig-credits"> 16664 <title>Credits</title> 16665 <para> 16666 Pierre-Elliott Bécue 16667 </para> 16668 </sect2> 16669 </sect1> 16670 16671 <sect1 id="sensible-browser"> 16672 <title>Sensible Browser Feature</title> 16673 <subtitle>Make the file browser behave</subtitle> 16674 16675 <sect2 id="sensible-browser-support"> 16676 <title>Support</title> 16677 <para> 16678 <emphasis role="bold">Since:</emphasis> NeoMutt 2016-09-10 16679 </para> 16680 <para> 16681 <emphasis role="bold">Dependencies:</emphasis> None 16682 </para> 16683 </sect2> 16684 16685 <sect2 id="sensible-browser-intro"> 16686 <title>Introduction</title> 16687 <para> 16688 The <quote>sensible browser</quote> is a set of small changes to 16689 NeoMutt's mailbox browser which make the browser behave in a more 16690 predictable way. 16691 </para> 16692 <para> 16693 The behavior is divided into two use cases: Fixed Order; Variable 16694 Order. 16695 </para> 16696 16697 <sect3 id="sensible-browser-sort-fixed"> 16698 <title>A Fixed Order of Mailboxes</title> 16699 <para> 16700 This is for users who like their mailboxes in a fixed order, e.g. 16701 alphabetical, or unsorted (in the order of the config file). 16702 </para> 16703 16704<screen> 16705<emphasis role="comment"># Fixed order</emphasis> 16706set sort_browser="alpha" 16707set sort_browser="unsorted" 16708</screen> 16709 16710 <para> 16711 When you first start the browser, e.g. <literal>c?</literal> your 16712 current mailbox will be highlighted. 16713 </para> 16714 <para> 16715 When you navigate to a parent mailbox (<quote>..</quote>) your old 16716 mailbox will be highlighted. 16717 </para> 16718 <para> 16719 <quote>..</quote> will always be listed at the top, however the 16720 rest of the list is sorted. 16721 </para> 16722 </sect3> 16723 16724 <sect3 id="sensible-browser-sort-variable"> 16725 <title>A Variable Order of Mailboxes</title> 16726 <para> 16727 This is for users who like their mailboxes sorted by 16728 a characteristic that changes, e.g. count of new mail, or the size 16729 of mailbox. 16730 </para> 16731 16732<screen> 16733<emphasis role="comment"># Variable order</emphasis> 16734set sort_browser="reverse-count" 16735set sort_browser="reverse-size" 16736</screen> 16737 16738 <para> 16739 When you first start the browser, e.g. <literal>c?</literal> the 16740 highlight will be on the first mailbox, e.g. the one with the most 16741 new mail. 16742 </para> 16743 <para> 16744 When you navigate to a parent mailbox (<quote>..</quote>) your old 16745 mailbox will be highlighted. 16746 </para> 16747 <para> 16748 <quote>..</quote> will always be listed at the top, however the 16749 rest of the list is sorted. 16750 </para> 16751 </sect3> 16752 </sect2> 16753 16754 <sect2 id="sensible-browser-see-also"> 16755 <title>See Also</title> 16756 <itemizedlist> 16757 <listitem> 16758 <para> 16759 <link linkend="folder-format">$folder_format</link> 16760 </para> 16761 </listitem> 16762 </itemizedlist> 16763 </sect2> 16764 16765 <sect2 id="sensible-browser-known-bugs"> 16766 <title>Known Bugs</title> 16767 <para> 16768 None 16769 </para> 16770 </sect2> 16771 16772 <sect2 id="sensible-browser-credits"> 16773 <title>Credits</title> 16774 <para> 16775 Pierre-Elliott Bécue, Haakon Riiser, Richard Russon 16776 </para> 16777 </sect2> 16778 </sect1> 16779 16780 <sect1 id="sidebar"> 16781 <title>Sidebar Feature</title> 16782 <subtitle>Overview of mailboxes</subtitle> 16783 16784 <sect2 id="sidebar-support"> 16785 <title>Support</title> 16786 <para> 16787 <emphasis role="bold">Since:</emphasis> NeoMutt 2016-09-10, NeoMutt 16788 1.7.0 16789 </para> 16790 <para> 16791 <emphasis role="bold">Dependencies:</emphasis> None 16792 </para> 16793 </sect2> 16794 16795 <sect2 id="sidebar-intro"> 16796 <title>Introduction</title> 16797 <para> 16798 The Sidebar shows a list of all your mailboxes. The list can be 16799 turned on and off, it can be themed and the list style can be 16800 configured. 16801 </para> 16802 <para> 16803 This part of the manual is a reference guide. If you want a simple 16804 introduction with examples see the 16805 <link linkend="intro-sidebar">Sidebar Howto</link>. If you just want 16806 to get started, you could use the sample 16807 <link linkend="sidebar-neomuttrc">Sidebar neomuttrc</link>. 16808 </para> 16809 </sect2> 16810 16811 <sect2 id="sidebar-variables"> 16812 <title>Variables</title> 16813 16814 <table id="table-sidebar-variables"> 16815 <title>Sidebar Variables</title> 16816 <tgroup cols="3"> 16817 <thead> 16818 <row> 16819 <entry>Name</entry> 16820 <entry>Type</entry> 16821 <entry>Default</entry> 16822 </row> 16823 </thead> 16824 <tbody> 16825 <row> 16826 <entry><literal>sidebar_component_depth</literal></entry> 16827 <entry>number</entry> 16828 <entry><literal>0</literal></entry> 16829 </row> 16830 <row> 16831 <entry><literal>sidebar_delim_chars</literal></entry> 16832 <entry>string</entry> 16833 <entry><literal>/.</literal></entry> 16834 </row> 16835 <row> 16836 <entry><literal>sidebar_divider_char</literal></entry> 16837 <entry>string</entry> 16838 <entry><literal>|</literal></entry> 16839 </row> 16840 <row> 16841 <entry><literal>sidebar_folder_indent</literal></entry> 16842 <entry>boolean</entry> 16843 <entry><literal>no</literal></entry> 16844 </row> 16845 <row> 16846 <entry><literal>sidebar_format</literal></entry> 16847 <entry>string</entry> 16848 <entry><literal>%D%* %n</literal></entry> 16849 </row> 16850 <row> 16851 <entry><literal>sidebar_indent_string</literal></entry> 16852 <entry>string</entry> 16853 <entry><literal>  </literal> (two spaces)</entry></row> 16854 <row> 16855 <entry><literal>sidebar_new_mail_only</literal></entry> 16856 <entry>boolean</entry> 16857 <entry><literal>no</literal></entry> 16858 </row> 16859 <row> 16860 <entry><literal>sidebar_next_new_wrap</literal></entry> 16861 <entry>boolean</entry> 16862 <entry><literal>no</literal></entry> 16863 </row> 16864 <row> 16865 <entry><literal>sidebar_non_empty_mailbox_only</literal></entry> 16866 <entry>boolean</entry> 16867 <entry><literal>no</literal></entry> 16868 </row> 16869 <row> 16870 <entry><literal>sidebar_on_right</literal></entry> 16871 <entry>boolean</entry> 16872 <entry><literal>no</literal></entry> 16873 </row> 16874 <row> 16875 <entry><literal>sidebar_short_path</literal></entry> 16876 <entry>boolean</entry> 16877 <entry><literal>no</literal></entry> 16878 </row> 16879 <row> 16880 <entry><literal>sidebar_sort_method</literal></entry> 16881 <entry>enum</entry> 16882 <entry><literal>unsorted</literal></entry> 16883 </row> 16884 <row> 16885 <entry><literal>sidebar_visible</literal></entry> 16886 <entry>boolean</entry> 16887 <entry><literal>no</literal></entry> 16888 </row> 16889 <row> 16890 <entry><literal>sidebar_width</literal></entry> 16891 <entry>number</entry> 16892 <entry><literal>20</literal></entry> 16893 </row> 16894 </tbody> 16895 </tgroup> 16896 </table> 16897 <para> 16898 For more details, and examples, about the 16899 <literal>$sidebar_format</literal>, see the 16900 <link linkend="intro-sidebar-format">Sidebar Intro</link>. 16901 </para> 16902 </sect2> 16903 16904 <sect2 id="sidebar-functions"> 16905 <title>Functions</title> 16906 <para> 16907 Sidebar adds the following functions to NeoMutt. By default, none of 16908 them are bound to keys. 16909 </para> 16910 16911 <table id="table-sidebar-functions"> 16912 <title>Sidebar Functions</title> 16913 <tgroup cols="3"> 16914 <thead> 16915 <row> 16916 <entry>Menus</entry> 16917 <entry>Function</entry> 16918 <entry>Description</entry> 16919 </row> 16920 </thead> 16921 <tbody> 16922 <row> 16923 <entry>index,pager</entry> 16924 <entry><literal><sidebar-next></literal></entry> 16925 <entry>Move the highlight to next mailbox</entry> 16926 </row> 16927 <row> 16928 <entry>index,pager</entry> 16929 <entry><literal><sidebar-next-new></literal></entry> 16930 <entry>Move the highlight to next mailbox with new mail</entry> 16931 </row> 16932 <row> 16933 <entry>index,pager</entry> 16934 <entry><literal><sidebar-open></literal></entry> 16935 <entry>Open highlighted mailbox</entry> 16936 </row> 16937 <row> 16938 <entry>index,pager</entry> 16939 <entry><literal><sidebar-page-down></literal></entry> 16940 <entry>Scroll the Sidebar down 1 page</entry> 16941 </row> 16942 <row> 16943 <entry>index,pager</entry> 16944 <entry><literal><sidebar-page-up></literal></entry> 16945 <entry>Scroll the Sidebar up 1 page</entry> 16946 </row> 16947 <row> 16948 <entry>index,pager</entry> 16949 <entry><literal><sidebar-prev></literal></entry> 16950 <entry>Move the highlight to previous mailbox</entry> 16951 </row> 16952 <row> 16953 <entry>index,pager</entry> 16954 <entry><literal><sidebar-prev-new></literal></entry> 16955 <entry>Move the highlight to previous mailbox with new mail</entry> 16956 </row> 16957 <row> 16958 <entry>index,pager</entry> 16959 <entry><literal><sidebar-toggle-visible></literal></entry> 16960 <entry>Make the Sidebar (in)visible</entry> 16961 </row> 16962 </tbody> 16963 </tgroup> 16964 </table> 16965 </sect2> 16966 16967 <sect2 id="sidebar-commands"> 16968 <title>Commands</title> 16969 <anchor id="sidebar-whitelist" /> 16970 <anchor id="unsidebar-whitelist" /> 16971 <cmdsynopsis> 16972 <command>sidebar_whitelist</command> 16973 <arg choice="plain"> 16974 <replaceable class="parameter">mailbox</replaceable> 16975 </arg> 16976 <arg choice="opt" rep="repeat"> 16977 <replaceable class="parameter">mailbox</replaceable> 16978 </arg> 16979 <command>unsidebar_whitelist</command> 16980 <group choice="req"> 16981 <arg choice="plain"> 16982 <replaceable class="parameter">*</replaceable> 16983 </arg> 16984 <arg choice="plain" rep="repeat"> 16985 <replaceable class="parameter">mailbox</replaceable> 16986 </arg> 16987 </group> 16988 </cmdsynopsis> 16989 <para> 16990 This command specifies mailboxes that will always be displayed in the 16991 sidebar, even if 16992 <link linkend="sidebar-new-mail-only">$sidebar_new_mail_only</link> 16993 is set and the mailbox does not contain new mail. 16994 </para> 16995 <para> 16996 The <quote>unsidebar_whitelist</quote> command is used to remove 16997 a mailbox from the list of whitelisted mailboxes. Use 16998 <quote>unsidebar_whitelist *</quote> to remove all mailboxes. 16999 </para> 17000 </sect2> 17001 17002 <sect2 id="sidebar-colors"> 17003 <title>Colors</title> 17004 17005 <table id="table-sidebar-colors"> 17006 <title>Sidebar Colors</title> 17007 <tgroup cols="3"> 17008 <thead> 17009 <row> 17010 <entry>Name</entry> 17011 <entry>Default Color</entry> 17012 <entry>Description</entry> 17013 </row> 17014 </thead> 17015 <tbody> 17016 <row> 17017 <entry><literal>sidebar_divider</literal></entry> 17018 <entry>default</entry> 17019 <entry> 17020 The dividing line between the Sidebar and the Index/Pager 17021 panels 17022 </entry> 17023 </row> 17024 <row> 17025 <entry><literal>sidebar_flagged</literal></entry> 17026 <entry>default</entry> 17027 <entry> 17028 Mailboxes containing flagged mail 17029 </entry> 17030 </row> 17031 <row> 17032 <entry><literal>sidebar_highlight</literal></entry> 17033 <entry>underline</entry> 17034 <entry> 17035 Cursor to select a mailbox 17036 </entry> 17037 </row> 17038 <row> 17039 <entry><literal>sidebar_indicator</literal></entry> 17040 <entry>neomutt <literal>indicator</literal></entry> 17041 <entry> 17042 The mailbox open in the Index panel 17043 </entry> 17044 </row> 17045 <row> 17046 <entry><literal>sidebar_new</literal></entry> 17047 <entry>default</entry> 17048 <entry> 17049 Mailboxes containing new mail 17050 </entry> 17051 </row> 17052 <row> 17053 <entry><literal>sidebar_ordinary</literal></entry> 17054 <entry>default</entry> 17055 <entry> 17056 Mailboxes that have no new/flagged mails, etc. 17057 </entry> 17058 </row> 17059 <row> 17060 <entry><literal>sidebar_spool_file</literal></entry> 17061 <entry>default</entry> 17062 <entry> 17063 Mailbox that receives incoming mail 17064 </entry> 17065 </row> 17066 <row> 17067 <entry><literal>sidebar_unread</literal></entry> 17068 <entry>default</entry> 17069 <entry> 17070 Mailboxes containing unread mail 17071 </entry> 17072 </row> 17073 </tbody> 17074 </tgroup> 17075 </table> 17076 <para> 17077 If the <literal>sidebar_indicator</literal> color isn't set, then the 17078 default NeoMutt indicator color will be used (the color used in the 17079 index panel). 17080 </para> 17081 </sect2> 17082 17083 <sect2 id="sidebar-sort"> 17084 <title>Sort</title> 17085 17086 <table id="table-sidebar-sort"> 17087 <title>Sidebar Sort</title> 17088 <tgroup cols="2"> 17089 <thead> 17090 <row> 17091 <entry>Sort</entry> 17092 <entry>Description</entry> 17093 </row> 17094 </thead> 17095 <tbody> 17096 <row> 17097 <entry><literal>alpha</literal></entry> 17098 <entry>Alphabetically by path</entry> 17099 </row> 17100 <row> 17101 <entry><literal>count</literal></entry> 17102 <entry>Total number of messages</entry> 17103 </row> 17104 <row> 17105 <entry><literal>desc</literal></entry> 17106 <entry>Descriptive name of the mailbox</entry> 17107 </row> 17108 <row> 17109 <entry><literal>flagged</literal></entry> 17110 <entry>Number of flagged messages</entry> 17111 </row> 17112 <row> 17113 <entry><literal>name</literal></entry> 17114 <entry>Alphabetically by path</entry> 17115 </row> 17116 <row> 17117 <entry><literal>new</literal></entry> 17118 <entry>Number of unread messages</entry> 17119 </row> 17120 <row> 17121 <entry><literal>path</literal></entry> 17122 <entry>Alphabetically by path</entry> 17123 </row> 17124 <row> 17125 <entry><literal>unread</literal></entry> 17126 <entry>Number of unread messages</entry> 17127 </row> 17128 <row> 17129 <entry><literal>unsorted</literal></entry> 17130 <entry>Order of the <literal>mailboxes</literal> command</entry> 17131 </row> 17132 </tbody> 17133 </tgroup> 17134 </table> 17135 </sect2> 17136 17137 <sect2 id="sidebar-neomuttrc"> 17138 <title>neomuttrc</title> 17139 17140<screen> 17141<emphasis role="comment"># Example NeoMutt config file for the sidebar feature.</emphasis> 17142 17143<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 17144<emphasis role="comment"># VARIABLES – shown with their default values</emphasis> 17145<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 17146<emphasis role="comment"># Should the Sidebar be shown?</emphasis> 17147set sidebar_visible = no 17148<emphasis role="comment"># How wide should the Sidebar be in screen columns?</emphasis> 17149 17150<emphasis role="comment"># Note: Some characters, e.g. Chinese, take up two columns each.</emphasis> 17151set sidebar_width = 20 17152<emphasis role="comment"># Should the mailbox paths be abbreviated?</emphasis> 17153set sidebar_short_path = no 17154<emphasis role="comment"># Number of top-level mailbox path subdirectories to truncate for display</emphasis> 17155set sidebar_component_depth = 0 17156<emphasis role="comment"># When abbreviating mailbox path names, use any of these characters as path</emphasis> 17157<emphasis role="comment"># separators. Only the part after the last separators will be shown.</emphasis> 17158<emphasis role="comment"># For file folders '/' is good. For IMAP folders, often '.' is useful.</emphasis> 17159set sidebar_delim_chars = '/.' 17160<emphasis role="comment"># If the mailbox path is abbreviated, should it be indented?</emphasis> 17161set sidebar_folder_indent = no 17162<emphasis role="comment"># Indent mailbox paths with this string.</emphasis> 17163set sidebar_indent_string = ' ' 17164<emphasis role="comment"># Make the Sidebar only display mailboxes that contain new, or flagged,</emphasis> 17165<emphasis role="comment"># mail.</emphasis> 17166set sidebar_new_mail_only = no 17167<emphasis role="comment"># Any mailboxes that are whitelisted will always be visible, even if the</emphasis> 17168<emphasis role="comment"># sidebar_new_mail_only option is enabled.</emphasis> 17169set sidebar_non_empty_mailbox_only = no 17170<emphasis role="comment"># Only show mailboxes that contain some mail</emphasis> 17171sidebar_whitelist '/home/user/mailbox1' 17172sidebar_whitelist '/home/user/mailbox2' 17173<emphasis role="comment"># When searching for mailboxes containing new mail, should the search wrap</emphasis> 17174<emphasis role="comment"># around when it reaches the end of the list?</emphasis> 17175set sidebar_next_new_wrap = no 17176<emphasis role="comment"># Show the Sidebar on the right-hand side of the screen</emphasis> 17177set sidebar_on_right = no 17178<emphasis role="comment"># The character to use as the divider between the Sidebar and the other NeoMutt</emphasis> 17179<emphasis role="comment"># panels.</emphasis> 17180set sidebar_divider_char = '|' 17181<emphasis role="comment"># Enable extended mailbox mode to calculate total, new, and flagged</emphasis> 17182<emphasis role="comment"># message counts for each mailbox.</emphasis> 17183set mail_check_stats 17184<emphasis role="comment"># Display the Sidebar mailboxes using this format string.</emphasis> 17185set sidebar_format = '%B%?F? [%F]?%* %?N?%N/?%S' 17186<emphasis role="comment"># Sort the mailboxes in the Sidebar using this method:</emphasis> 17187<emphasis role="comment"># count – total number of messages</emphasis> 17188<emphasis role="comment"># flagged – number of flagged messages</emphasis> 17189<emphasis role="comment"># new – number of new messages</emphasis> 17190<emphasis role="comment"># path – mailbox path</emphasis> 17191<emphasis role="comment"># unsorted – do not sort the mailboxes</emphasis> 17192set sidebar_sort_method = 'unsorted' 17193<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 17194<emphasis role="comment"># FUNCTIONS – shown with an example mapping</emphasis> 17195<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 17196<emphasis role="comment"># Move the highlight to the previous mailbox</emphasis> 17197bind index,pager \Cp sidebar-prev 17198<emphasis role="comment"># Move the highlight to the next mailbox</emphasis> 17199bind index,pager \Cn sidebar-next 17200<emphasis role="comment"># Open the highlighted mailbox</emphasis> 17201bind index,pager \Co sidebar-open 17202<emphasis role="comment"># Move the highlight to the previous page</emphasis> 17203<emphasis role="comment"># This is useful if you have a LOT of mailboxes.</emphasis> 17204bind index,pager <F3> sidebar-page-up 17205<emphasis role="comment"># Move the highlight to the next page</emphasis> 17206<emphasis role="comment"># This is useful if you have a LOT of mailboxes.</emphasis> 17207bind index,pager <F4> sidebar-page-down 17208<emphasis role="comment"># Move the highlight to the previous mailbox containing new, or flagged,</emphasis> 17209<emphasis role="comment"># mail.</emphasis> 17210bind index,pager <F5> sidebar-prev-new 17211<emphasis role="comment"># Move the highlight to the next mailbox containing new, or flagged, mail.</emphasis> 17212bind index,pager <F6> sidebar-next-new 17213<emphasis role="comment"># Toggle the visibility of the Sidebar.</emphasis> 17214bind index,pager B sidebar-toggle-visible 17215<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 17216<emphasis role="comment"># COLORS – some unpleasant examples are given</emphasis> 17217<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 17218<emphasis role="comment"># Note: All color operations are of the form:</emphasis> 17219<emphasis role="comment"># color OBJECT FOREGROUND BACKGROUND</emphasis> 17220<emphasis role="comment"># Color of the current, open, mailbox</emphasis> 17221<emphasis role="comment"># Note: This is a general NeoMutt option which colors all selected items.</emphasis> 17222color indicator cyan black 17223<emphasis role="comment"># Sidebar-specific color of the selected item</emphasis> 17224color sidebar_indicator cyan black 17225<emphasis role="comment"># Color of the highlighted, but not open, mailbox.</emphasis> 17226color sidebar_highlight black color8 17227<emphasis role="comment"># Color of the divider separating the Sidebar from NeoMutt panels</emphasis> 17228color sidebar_divider color8 black 17229<emphasis role="comment"># Color to give mailboxes containing flagged mail</emphasis> 17230color sidebar_flagged red black 17231<emphasis role="comment"># Color to give mailboxes containing new mail</emphasis> 17232color sidebar_new green black 17233<emphasis role="comment"># Color to give mailboxes containing no new/flagged mail, etc.</emphasis> 17234color sidebar_ordinary color245 default 17235<emphasis role="comment"># Color to give the spool_file mailbox</emphasis> 17236color sidebar_spool_file color207 default 17237<emphasis role="comment"># Color to give mailboxes containing no unread mail</emphasis> 17238color sidebar_unread color136 default 17239<emphasis role="comment"># --------------------------------------------------------------------------</emphasis> 17240 17241<emphasis role="comment"># vim: syntax=neomuttrc</emphasis> 17242</screen> 17243 17244 </sect2> 17245 17246 <sect2 id="sidebar-see-also"> 17247 <title>See Also</title> 17248 <itemizedlist> 17249 <listitem> 17250 <para> 17251 <link linkend="regex">Regular Expressions</link> 17252 </para> 17253 </listitem> 17254 <listitem> 17255 <para> 17256 <link linkend="patterns">Patterns</link> 17257 </para> 17258 </listitem> 17259 <listitem> 17260 <para> 17261 <link linkend="color">Color command</link> 17262 </para> 17263 </listitem> 17264 <listitem> 17265 <para> 17266 <link linkend="notmuch">notmuch feature</link> 17267 </para> 17268 </listitem> 17269 </itemizedlist> 17270 </sect2> 17271 17272 <sect2 id="sidebar-known-bugs"> 17273 <title>Known Bugs</title> 17274 <para> 17275 None 17276 </para> 17277 </sect2> 17278 17279 <sect2 id="sidebar-credits"> 17280 <title>Credits</title> 17281 <para> 17282 Justin Hibbits, Thomer M. Gil, David Sterba, Evgeni Golov, 17283 Fabian Groffen, Jason DeTiberus, Stefan Assmann, Steve Kemp, 17284 Terry Chan, Tyler Earnest, Richard Russon 17285 </para> 17286 </sect2> 17287 </sect1> 17288 17289 <sect1 id="skip-quoted-patch"> 17290 <title>Skip Quoted Feature</title> 17291 <subtitle>Managing quoted text in the pager</subtitle> 17292 17293 <sect2 id="skip-quoted-support"> 17294 <title>Support</title> 17295 <para> 17296 <emphasis role="bold">Since:</emphasis> 17297 <literal>$skip_quoted_offset</literal> in NeoMutt 17298 2016-03-28, <literal>$toggle_quoted_show_levels</literal> in 17299 NeoMutt 2019-10-25, <literal><skip-headers></literal> 17300 in NeoMutt 2021-02-05 17301 </para> 17302 <para> 17303 <emphasis role="bold">Dependencies:</emphasis> None 17304 </para> 17305 </sect2> 17306 17307 <sect2 id="skip-quoted-intro"> 17308 <title>Introduction</title> 17309 <para> 17310 When viewing an email, the 17311 <literal><skip-quoted></literal> function (by default 17312 the <literal>S</literal> key) will scroll past any email 17313 headers or quoted text. Sometimes, a little context is 17314 useful. By setting the 17315 <literal>$skip_quoted_offset</literal> variable, you can 17316 select how much of the quoted text is left visible. 17317 </para> 17318 <para> 17319 When using the <literal><toggle-quoted></literal> 17320 function (by default the <literal>T</literal> key), it can 17321 be convenient to hide text that has been quoted multiple 17322 times while still leaving quoted text that is relevant to 17323 the unquoted reply intact. This can be done by setting the 17324 <literal>$toggle_quoted_show_levels</literal> variable. 17325 </para> 17326 <para> 17327 Also, it can be handy to jump directly to the start of the 17328 email body with the <literal><skip-headers></literal> 17329 function (by default the <literal>H</literal>key). 17330 </para> 17331 </sect2> 17332 17333 <sect2 id="skip-quoted-functions"> 17334 <title>Functions</title> 17335 17336 <table id="table-quoted-functions"> 17337 <title>Skip Quoted Functions</title> 17338 <tgroup cols="4"> 17339 <thead> 17340 <row> 17341 <entry>Menus</entry> 17342 <entry>Default Key</entry> 17343 <entry>Function</entry> 17344 <entry>Description</entry> 17345 </row> 17346 </thead> 17347 <tbody> 17348 <row> 17349 <entry>pager</entry> 17350 <entry>H</entry> 17351 <entry><literal><skip-headers></literal></entry> 17352 <entry> 17353 jump to first line after headers 17354 </entry> 17355 </row> 17356 </tbody> 17357 </tgroup> 17358 </table> 17359 </sect2> 17360 17361 <sect2 id="skip-quoted-variables"> 17362 <title>Variables</title> 17363 17364 <table id="table-skip-quoted-variables"> 17365 <title>Skip-Quoted Variables</title> 17366 <tgroup cols="3"> 17367 <thead> 17368 <row> 17369 <entry>Name</entry> 17370 <entry>Type</entry> 17371 <entry>Default</entry> 17372 </row> 17373 </thead> 17374 <tbody> 17375 <row> 17376 <entry><literal>pager_skip_quoted_context</literal></entry> 17377 <entry>number</entry> 17378 <entry>0</entry> 17379 </row> 17380 <row> 17381 <entry><literal>skip_quoted_offset</literal></entry> 17382 <entry>synonym</entry> 17383 <entry>pager_skip_quoted_context</entry> 17384 </row> 17385 <row> 17386 <entry><literal>toggle_quoted_show_levels</literal></entry> 17387 <entry>number</entry> 17388 <entry>0</entry> 17389 </row> 17390 </tbody> 17391 </tgroup> 17392 </table> 17393 </sect2> 17394 17395 <sect2 id="skip-quoted-neomuttrc"> 17396 <title>neomuttrc</title> 17397 17398<screen> 17399<emphasis role="comment"># Example NeoMutt config file for the skip-quoted feature.</emphasis> 17400 17401<emphasis role="comment"># The 'S' (skip-quoted) command scrolls the pager past the quoted text (usually</emphasis> 17402<emphasis role="comment"># indented with '> '. Setting 'pager_skip_quoted_context leaves some lines</emphasis> 17403<emphasis role="comment"># of quoted text on screen for context.</emphasis> 17404 17405<emphasis role="comment"># Show three quoted lines before the reply</emphasis> 17406set pager_skip_quoted_context = 3 17407 17408<emphasis role="comment"># The 'T' (toggle-quoted) command hides quoted text, but can</emphasis> 17409<emphasis role="comment"># be limited to only hiding deeply-nested quotes.</emphasis> 17410 17411<emphasis role="comment"># Preserve the first level of quoted text</emphasis> 17412set toggle_quoted_show_levels = 1 17413 17414<emphasis role="comment"># vim: syntax=neomuttrc</emphasis> 17415</screen> 17416 17417 </sect2> 17418 17419 <sect2 id="skip-quoted-known-bugs"> 17420 <title>Known Bugs</title> 17421 <para> 17422 None 17423 </para> 17424 </sect2> 17425 17426 <sect2 id="skip-quoted-credits"> 17427 <title>Credits</title> 17428 <para> 17429 David Sterba, Richard Russon 17430 </para> 17431 </sect2> 17432 </sect1> 17433 17434 <sect1 id="status-color"> 17435 <title>Status Color Feature</title> 17436 <subtitle>Custom rules for theming the status bar</subtitle> 17437 17438 <sect2 id="status-color-support"> 17439 <title>Support</title> 17440 <para> 17441 <emphasis role="bold">Since:</emphasis> NeoMutt 2016-03-07 17442 </para> 17443 <para> 17444 <emphasis role="bold">Dependencies:</emphasis> None 17445 </para> 17446 </sect2> 17447 17448 <sect2 id="status-color-intro"> 17449 <title>Introduction</title> 17450 <para> 17451 The <quote>status-color</quote> feature allows you to theme different 17452 parts of the status bar (also when it's used by the index). 17453 </para> 17454 <para> 17455 Unlike normal color commands, <literal>color status</literal> can now 17456 take up to 2 extra parameters (regex, num). 17457 </para> 17458 </sect2> 17459 17460 <sect2 id="status-color-commands"> 17461 <title>Commands</title> 17462 <cmdsynopsis> 17463 <command>color</command> 17464 <arg choice="plain"> 17465 <option>status</option> 17466 </arg> 17467 <arg choice="plain"> 17468 <replaceable class="parameter">foreground</replaceable> 17469 </arg> 17470 <arg choice="plain"> 17471 <replaceable class="parameter">background</replaceable> 17472 </arg> 17473 <group choice="opt"> 17474 <arg choice="plain"> 17475 <replaceable class="parameter">regex</replaceable> 17476 </arg> 17477 <group choice="opt"> 17478 <arg choice="plain"> 17479 <replaceable class="parameter">num</replaceable> 17480 </arg> 17481 </group> 17482 </group> 17483 </cmdsynopsis> 17484 <para> 17485 With zero parameters, NeoMutt will set the default color for the 17486 entire status bar. 17487 </para> 17488 <para> 17489 With one parameter, NeoMutt will only color the parts matching the 17490 regex. 17491 </para> 17492 <para> 17493 With two parameters, NeoMutt will only color the num'th sub-match of 17494 the regex. 17495 </para> 17496 </sect2> 17497 17498 <sect2 id="status-color-colors"> 17499 <title>Colors</title> 17500 17501 <table id="table-status-color-colors"> 17502 <title>Status Colors</title> 17503 <tgroup cols="3"> 17504 <thead> 17505 <row> 17506 <entry>Name</entry> 17507 <entry>Default Color</entry> 17508 <entry>Description</entry> 17509 </row> 17510 </thead> 17511 <tbody> 17512 <row> 17513 <entry>status</entry> 17514 <entry><literal>reverse</literal></entry> 17515 <entry>Status bar</entry> 17516 </row> 17517 </tbody> 17518 </tgroup> 17519 </table> 17520 </sect2> 17521 17522 <sect2 id="status-color-neomuttrc"> 17523 <title>neomuttrc</title> 17524 17525<screen> 17526<emphasis role="comment"># Example NeoMutt config file for the status-color feature.</emphasis> 17527 17528<emphasis role="comment"># The 'status-color' feature allows you to theme different parts of</emphasis> 17529<emphasis role="comment"># the status bar (also when it's used by the index).</emphasis> 17530 17531<emphasis role="comment"># For the examples below, set some defaults</emphasis> 17532set status_format='-%r-NeoMutt: %f [Msgs:%?M?%M/?%m%?n? New:%n?%?o? Old:%o?%?d? Del:%d?%?F? \ 17533 Flag:%F?%?t? Tag:%t?%?p? Post:%p?%?b? Inc:%b?%?l? %l?]---(%s/%S)-%>-(%P)---' 17534set index_format='%4C %Z %{%b %d} %-15.15L (%?l?%4l&%4c?) %s' 17535set use_threads=yes 17536set sort=last-date-received 17537set sort_aux=date 17538<emphasis role="comment"># 'status color' can take up to 2 extra parameters</emphasis> 17539<emphasis role="comment"># color status foreground background [ regex [ num ]]</emphasis> 17540<emphasis role="comment"># 0 extra parameters</emphasis> 17541<emphasis role="comment"># Set the default color for the entire status line</emphasis> 17542color status blue white 17543<emphasis role="comment"># 1 extra parameter</emphasis> 17544<emphasis role="comment"># Set the color for a matching pattern</emphasis> 17545<emphasis role="comment"># color status foreground background regex</emphasis> 17546<emphasis role="comment"># Highlight New, Deleted, or Flagged emails</emphasis> 17547color status brightred white '(New|Del|Flag):[0-9]+' 17548<emphasis role="comment"># Highlight mailbox ordering if it's different from the default</emphasis> 17549<emphasis role="comment"># First, highlight anything (*/*)</emphasis> 17550color status brightred default '\([^)]+/[^)]+\)' 17551<emphasis role="comment"># Then override the color for one specific case</emphasis> 17552color status default default '\(threads/last-date-received\)' 17553<emphasis role="comment"># 2 extra parameters</emphasis> 17554<emphasis role="comment"># Set the color for the nth submatch of a pattern</emphasis> 17555<emphasis role="comment"># color status foreground background regex num</emphasis> 17556<emphasis role="comment"># Highlight the contents of the []s but not the [] themselves</emphasis> 17557color status red default '\[([^]]+)\]' 1 17558<emphasis role="comment"># The '1' refers to the first regex submatch, which is the inner</emphasis> 17559<emphasis role="comment"># part in ()s</emphasis> 17560<emphasis role="comment"># Highlight the mailbox</emphasis> 17561color status brightwhite default 'NeoMutt: ([^ ]+)' 1 17562<emphasis role="comment"># Search for 'NeoMutt: ' but only highlight what comes after it</emphasis> 17563 17564<emphasis role="comment"># vim: syntax=neomuttrc</emphasis> 17565</screen> 17566 17567 </sect2> 17568 17569 <sect2 id="status-color-see-also"> 17570 <title>See Also</title> 17571 <itemizedlist> 17572 <listitem> 17573 <para> 17574 <link linkend="compile-time-features">Compile-Time Features</link> 17575 </para> 17576 </listitem> 17577 <listitem> 17578 <para> 17579 <link linkend="regex">Regular Expressions</link> 17580 </para> 17581 </listitem> 17582 <listitem> 17583 <para> 17584 <link linkend="patterns">Patterns</link> 17585 </para> 17586 </listitem> 17587 <listitem> 17588 <para> 17589 <link linkend="index-color">index-color feature</link> 17590 </para> 17591 </listitem> 17592 <listitem> 17593 <para> 17594 <link linkend="color">Color command</link> 17595 </para> 17596 </listitem> 17597 </itemizedlist> 17598 </sect2> 17599 17600 <sect2 id="status-color-known-bugs"> 17601 <title>Known Bugs</title> 17602 <para> 17603 None 17604 </para> 17605 </sect2> 17606 17607 <sect2 id="status-color-credits"> 17608 <title>Credits</title> 17609 <para> 17610 David Sterba, Thomas Glanzmann, Kirill A. Shutemov, Richard Russon 17611 </para> 17612 </sect2> 17613 </sect1> 17614 17615 <sect1 id="tls-sni"> 17616 <title>TLS-SNI Feature</title> 17617 <subtitle>Negotiate with a server for a TLS/SSL certificate</subtitle> 17618 17619 <sect2 id="tls-sni-support"> 17620 <title>Support</title> 17621 <para> 17622 <emphasis role="bold">Since:</emphasis> NeoMutt 2016-03-07 17623 </para> 17624 <variablelist> 17625 <varlistentry> 17626 <term> 17627 <emphasis role="bold">Dependencies:</emphasis> 17628 </term> 17629 <listitem> 17630 <para> 17631 OpenSSL 17632 </para> 17633 </listitem> 17634 </varlistentry> 17635 </variablelist> 17636 </sect2> 17637 17638 <sect2 id="tls-sni-intro"> 17639 <title>Introduction</title> 17640 <para> 17641 The <quote>TLS-SNI</quote> feature adds support for TLS virtual 17642 hosting. If your mail server doesn't support this everything will 17643 still work normally. 17644 </para> 17645 <para> 17646 TLS supports sending the expected server hostname during the 17647 handshake, via the SNI extension. This can be used to select a server 17648 certificate to issue to the client, permitting virtual-hosting 17649 without requiring multiple IP addresses. 17650 </para> 17651 <para> 17652 This has been tested against Exim 4.80, which optionally logs SNI and 17653 can perform vhosting. 17654 </para> 17655 <para> 17656 To verify TLS SNI support by a server, you can use: 17657 </para> 17658 17659<screen> 17660openssl s_client -host <imap server> -port <port> -tls1 -servername <imap server> 17661</screen> 17662 17663 </sect2> 17664 17665 <sect2 id="tls-sni-known-bugs"> 17666 <title>Known Bugs</title> 17667 <para> 17668 None 17669 </para> 17670 </sect2> 17671 17672 <sect2 id="tls-sni-credits"> 17673 <title>Credits</title> 17674 <para> 17675 Jeremy Katz, Phil Pennock, Richard Russon 17676 </para> 17677 </sect2> 17678 </sect1> 17679 17680 <sect1 id="trash-folder"> 17681 <title>Trash Folder Feature</title> 17682 <subtitle>Automatically move deleted emails to a trash bin</subtitle> 17683 17684 <sect2 id="trash-folder-support"> 17685 <title>Support</title> 17686 <para> 17687 <emphasis role="bold">Since:</emphasis> NeoMutt 2016-09-10, NeoMutt 17688 1.7.0 17689 </para> 17690 <variablelist> 17691 <varlistentry> 17692 <term> 17693 <emphasis role="bold">Dependencies:</emphasis> 17694 </term> 17695 <listitem> 17696 <para> 17697 If IMAP is enabled, the trash folder will use it wisely 17698 </para> 17699 </listitem> 17700 </varlistentry> 17701 </variablelist> 17702 </sect2> 17703 17704 <sect2 id="trash-folder-intro"> 17705 <title>Introduction</title> 17706 <para> 17707 In NeoMutt, when you <quote>delete</quote> an email it is first 17708 marked deleted. The email isn't really gone until 17709 <link linkend="index-map"><sync-mailbox></link> is called. This 17710 happens when the user leaves the folder, or the function is called 17711 manually. 17712 </para> 17713 <para> 17714 After <literal><sync-mailbox></literal> has been called the 17715 email is gone forever. 17716 </para> 17717 <para> 17718 The <link linkend="trash">$trash</link> variable defines a folder in 17719 which to keep old emails. As before, first you mark emails for 17720 deletion. When <sync-mailbox> is called the emails are moved to 17721 the trash folder. 17722 </para> 17723 <para> 17724 The <literal>$trash</literal> path can be either a full directory, or 17725 be relative to the <link linkend="folder">$folder</link> variable, 17726 like the <literal>mailboxes</literal> command. 17727 </para> 17728 <note> 17729 <para> 17730 Emails deleted from the trash folder are gone forever. 17731 </para> 17732 </note> 17733 </sect2> 17734 17735 <sect2 id="trash-folder-variables"> 17736 <title>Variables</title> 17737 17738 <table id="table-trash-variables"> 17739 <title>Trash Variables</title> 17740 <tgroup cols="3"> 17741 <thead> 17742 <row> 17743 <entry>Name</entry> 17744 <entry>Type</entry> 17745 <entry>Default</entry> 17746 </row> 17747 </thead> 17748 <tbody> 17749 <row> 17750 <entry>trash</entry> 17751 <entry>string</entry> 17752 <entry>(none)</entry> 17753 </row> 17754 </tbody> 17755 </tgroup> 17756 </table> 17757 </sect2> 17758 17759 <sect2 id="trash-folder-functions"> 17760 <title>Functions</title> 17761 17762 <table id="table-trash-functions"> 17763 <title>Trash Functions</title> 17764 <tgroup cols="4"> 17765 <thead> 17766 <row> 17767 <entry>Menus</entry> 17768 <entry>Default Key</entry> 17769 <entry>Function</entry> 17770 <entry>Description</entry> 17771 </row> 17772 </thead> 17773 <tbody> 17774 <row> 17775 <entry>index,pager</entry> 17776 <entry>(none)</entry> 17777 <entry><literal><purge-message></literal></entry> 17778 <entry> 17779 really delete the current entry, bypassing the trash folder 17780 </entry> 17781 </row> 17782 </tbody> 17783 </tgroup> 17784 </table> 17785 </sect2> 17786 17787 <sect2 id="trash-folder-neomuttrc"> 17788 <title>neomuttrc</title> 17789 17790<screen> 17791<emphasis role="comment"># Example NeoMutt config file for the 'trash' feature.</emphasis> 17792 17793<emphasis role="comment"># This feature defines a new 'trash' folder.</emphasis> 17794 17795<emphasis role="comment"># When mail is deleted it will be moved to this folder.</emphasis> 17796 17797<emphasis role="comment"># Folder in which to put deleted emails</emphasis> 17798set trash='+Trash' 17799set trash='/home/flatcap/Mail/Trash' 17800<emphasis role="comment"># The default delete key 'd' will move an email to the 'trash' folder</emphasis> 17801<emphasis role="comment"># Bind 'D' to REALLY delete an email</emphasis> 17802bind index D purge-message 17803<emphasis role="comment"># Note: Deleting emails from the 'trash' folder will REALLY delete them.</emphasis> 17804 17805<emphasis role="comment"># vim: syntax=neomuttrc</emphasis> 17806</screen> 17807 17808 </sect2> 17809 17810 <sect2 id="trash-folder-see-also"> 17811 <title>See Also</title> 17812 <itemizedlist> 17813 <listitem> 17814 <para> 17815 <link linkend="folder-hook">folder-hook</link> 17816 </para> 17817 </listitem> 17818 </itemizedlist> 17819 </sect2> 17820 17821 <sect2 id="trash-folder-known-bugs"> 17822 <title>Known Bugs</title> 17823 <para> 17824 None 17825 </para> 17826 </sect2> 17827 17828 <sect2 id="trash-folder-credits"> 17829 <title>Credits</title> 17830 <para> 17831 Cedric Duval, Benjamin Kuperman, Paul Miller, Richard Russon 17832 </para> 17833 </sect2> 17834 </sect1> 17835 17836 <sect1 id="use-threads-feature"> 17837 <title>Use Threads Feature</title> 17838 <subtitle>Improve the experience with viewing threads in the 17839 index</subtitle> 17840 17841 <sect2 id="use-threads-support"> 17842 <title>Support</title> 17843 <para> 17844 <emphasis role="bold">Since:</emphasis> NeoMutt 2021-08-01 17845 </para> 17846 <para> 17847 <emphasis role="bold">Dependencies:</emphasis> None 17848 </para> 17849 </sect2> 17850 17851 <sect2 id="use-threads-intro"> 17852 <title>Introduction</title> 17853 <para> 17854 The <quote>Use Threads</quote> feature adds a new config 17855 variable to allow more precise control of how threads are 17856 displayed in the index. Whether threads are in use is now 17857 orthogonal from how messages are sorted. 17858 </para> 17859 </sect2> 17860 17861 <sect2 id="use-thread-functions"> 17862 <title>Functions</title> 17863 <para> 17864 The <quote>Use Threads</quote> feature adds no new functions 17865 to NeoMutt. The existing functions 17866 <literal><sort-mailbox></literal> and 17867 <literal><sort-reverse></literal> are updated to 17868 toggle the state of <literal>$use_threads</literal> once it 17869 has been set, while preserving backwards-compatible behavior 17870 on <literal>$sort</literal> if this feature is not used. 17871 </para> 17872 </sect2> 17873 17874 <sect2 id="use-threads-variables"> 17875 <title>Variables</title> 17876 <para> 17877 The <quote>Use Threads</quote> feature adds one new config 17878 variable, <link linkend="use-threads">$use_threads</link>, 17879 which is an enumeration of possible thread views. The 17880 variable defaults to unset for the original behavior of 17881 overloading <link linkend="sort">$sort=threads</link> to 17882 enable sorting. It can be set to <literal>flat</literal> 17883 (or <literal>no</literal>) for an unthreaded view based on 17884 <literal>$sort</literal>, to <literal>threads</literal> (or 17885 <literal>yes</literal>) for a threaded view where roots 17886 appear above children, or to <literal>reverse</literal> for 17887 a threaded view where children appear above roots. 17888 </para> 17889 <para> 17890 When sorting by threads, the value of <link 17891 linkend="sort">$sort</link> determines which thread floats 17892 to the top. If <literal>$sort</literal> does not contain 17893 <literal>reverse-</literal>, the latest thread goes to the 17894 bottom for <literal>use_threads=threads</literal> and to the 17895 top for <literal>use_threads=reverse</literal>; the 17896 direction of float is swapped if <literal>$sort</literal> 17897 also uses <literal>reverse-</literal>. If 17898 <literal>$sort</literal> includes <literal>last-</literal>, 17899 the overall thread is sorted by its descendant at any depth 17900 which would sort last in a flat view; otherwise, the overall 17901 thread is sorted solely by the thread root. The 17902 <literal>last-</literal> prefix is ignored when 17903 <literal>use_threads=flat</literal>. 17904 </para> 17905 <para> 17906 Within a single thread, the value of <link 17907 linkend="sort-aux">$sort_aux</link> determines how siblings 17908 are sorted. The same prefixes apply as for 17909 <literal>$sort</literal>, although it is less common to use 17910 the <literal>last-</literal> prefix. 17911 </para> 17912 <para> 17913 The <quote>Use Threads</quote> feature also modifies the 17914 existing config variable <link 17915 linkend="status-format">$status_format</link>, adding the 17916 <literal>%T</literal> expando which shows the current 17917 threading method. 17918 </para> 17919 </sect2> 17920 17921 <sect2 id="use-threads-value"> 17922 <title>Use Threads</title> 17923 17924 <table> 17925 <title>Use Threads</title> 17926 <tgroup cols="3"> 17927 <thead> 17928 <row> 17929 <entry>Name</entry> 17930 <entry>Type</entry> 17931 <entry>Default</entry> 17932 </row> 17933 </thead> 17934 <tbody> 17935 <row> 17936 <entry><literal>use_threads</literal></entry> 17937 <entry>enum</entry> 17938 <entry><literal>unset</literal></entry> 17939 </row> 17940 </tbody> 17941 </tgroup> 17942 </table> 17943 </sect2> 17944 17945 <sect2 id="use-threads-neomuttrc"> 17946 <title>neomuttrc</title> 17947 17948<screen> 17949<emphasis role="comment"># Example NeoMutt config file for the use-threads feature.</emphasis> 17950 17951<emphasis role="comment"># ------------------------------------------------------------</emphasis> 17952<emphasis role="comment"># Default configuration: flat view sorted by date</emphasis> 17953<emphasis role="comment"># selecting threads with <sort-mailbox> changes $sort</emphasis> 17954<emphasis role="comment">#set use_threads=unset sort=date sort_aux=date</emphasis> 17955<emphasis role="comment"># Modern configuration: explicit flat view sorted by date</emphasis> 17956<emphasis role="comment"># selecting threads with <sort-mailbox> changes $use_threads</emphasis> 17957<emphasis role="comment">set use_threads=no sort=date sort_aux=date</emphasis> 17958<emphasis role="comment"># Anne 12:01 cover letter for thread 1</emphasis> 17959<emphasis role="comment"># Anne 12:02 part 1 of thread 1</emphasis> 17960<emphasis role="comment"># Anne 12:03 part 2 of thread 1</emphasis> 17961<emphasis role="comment"># Anne 12:04 part 3 of thread 1</emphasis> 17962<emphasis role="comment"># Barbara 12:05 thread 2</emphasis> 17963<emphasis role="comment"># Claire 12:06 thread 3</emphasis> 17964<emphasis role="comment"># Diane 12:07 re: part 2 of thread 1</emphasis> 17965<emphasis role="comment"># Erica 12:08 re: thread 2</emphasis> 17966 17967<emphasis role="comment"># ------------------------------------------------------------</emphasis> 17968<emphasis role="comment"># Legacy configuration: sorting threads by date started</emphasis> 17969<emphasis role="comment">#set sort=threads sort_aux=date</emphasis> 17970<emphasis role="comment"># Modern configuration for the same</emphasis> 17971<emphasis role="comment"># Latest root message sorts last</emphasis> 17972set use_threads=yes sort=date sort_aux=date 17973<emphasis role="comment"># Anne 12:01 cover letter for thread 1</emphasis> 17974<emphasis role="comment"># Anne 12:02 |->part 1 of thread 1</emphasis> 17975<emphasis role="comment"># Anne 12:03 |->part 2 of thread 1</emphasis> 17976<emphasis role="comment"># Diane 12:07 | `->re: part 2 of thread 1</emphasis> 17977<emphasis role="comment"># Anne 12:04 `->part 3 of thread 1</emphasis> 17978<emphasis role="comment"># Barbara 12:05 thread 2</emphasis> 17979<emphasis role="comment"># Erica 12:08 `->re: thread 2</emphasis> 17980<emphasis role="comment"># Claire 12:06 thread 3</emphasis> 17981 17982<emphasis role="comment"># ------------------------------------------------------------</emphasis> 17983<emphasis role="comment"># Legacy configuration: display threads upside-down</emphasis> 17984<emphasis role="comment">#set sort=reverse-threads sort_aux=date</emphasis> 17985<emphasis role="comment"># Modern configuration for the same</emphasis> 17986<emphasis role="comment"># Latest root message sorts first</emphasis> 17987set use_threads=reverse sort=date sort_aux=date 17988<emphasis role="comment"># Claire 12:06 thread 3</emphasis> 17989<emphasis role="comment"># Erica 12:08 ,->re: thread 2</emphasis> 17990<emphasis role="comment"># Barbara 12:05 thread 2</emphasis> 17991<emphasis role="comment"># Anne 12:04 ,->part 3 of thread 1</emphasis> 17992<emphasis role="comment"># Diane 12:07 | ,->re: part 2 of thread 1</emphasis> 17993<emphasis role="comment"># Anne 12:03 |->part 2 of thread 1</emphasis> 17994<emphasis role="comment"># Anne 12:02 |->part 1 of thread 1</emphasis> 17995<emphasis role="comment"># Anne 12:01 cover letter for thread 1</emphasis> 17996 17997<emphasis role="comment"># ------------------------------------------------------------</emphasis> 17998<emphasis role="comment"># Legacy configuration: recently active thread/subthread first</emphasis> 17999<emphasis role="comment">#set sort=threads sort_aux=reverse-last-date</emphasis> 18000<emphasis role="comment"># Modern configuration for the same</emphasis> 18001<emphasis role="comment"># Note that subthreads are also rearranged</emphasis> 18002set use_threads=threads sort=reverse-last-date sort_aux=reverse-last-date 18003<emphasis role="comment"># Barbara 12:05 thread 2</emphasis> 18004<emphasis role="comment"># Erica 12:08 `->re: thread 2</emphasis> 18005<emphasis role="comment"># Anne 12:01 cover letter for thread 1</emphasis> 18006<emphasis role="comment"># Anne 12:03 |->part 2 of thread 1</emphasis> 18007<emphasis role="comment"># Diane 12:07 | `->re: part 2 of thread 1</emphasis> 18008<emphasis role="comment"># Anne 12:04 |->part 3 of thread 1</emphasis> 18009<emphasis role="comment"># Anne 12:02 `->part 1 of thread 1</emphasis> 18010<emphasis role="comment"># Claire 12:06 thread 3</emphasis> 18011 18012<emphasis role="comment"># ------------------------------------------------------------</emphasis> 18013<emphasis role="comment"># Modern configuration: threads keep date order, recently active thread last</emphasis> 18014<emphasis role="comment"># (not possible with legacy configuration)</emphasis> 18015set use_threads=threads sort=last-date sort_aux=date 18016<emphasis role="comment"># Claire 12:06 thread 3</emphasis> 18017<emphasis role="comment"># Anne 12:01 cover letter for thread 1</emphasis> 18018<emphasis role="comment"># Anne 12:02 |->part 1 of thread 1</emphasis> 18019<emphasis role="comment"># Anne 12:03 |->part 2 of thread 1</emphasis> 18020<emphasis role="comment"># Diane 12:07 | `->re: part 2 of thread 1</emphasis> 18021<emphasis role="comment"># Anne 12:04 `->part 3 of thread 1</emphasis> 18022<emphasis role="comment"># Barbara 12:05 thread 2</emphasis> 18023<emphasis role="comment"># Erica 12:08 `->re: thread 2</emphasis> 18024 18025<emphasis role="comment"># vim: syntax=neomuttrc</emphasis> 18026</screen> 18027 18028 </sect2> 18029 18030 <sect2 id="use-threads-known-bugs"> 18031 <title>Known Bugs</title> 18032 <para> 18033 Even though <literal>use_threads</literal> accepts the 18034 values <literal>yes</literal> and <literal>no</literal>, it 18035 does not behave like a boolean or quad-option variable. A 18036 bare <literal>set use_threads</literal> performs a query 18037 rather than setting it to <literal>yes</literal>, and the 18038 variable is not usable with <literal>toggle</literal>. 18039 </para> 18040 </sect2> 18041 18042 <sect2 id="use-threads-credits"> 18043 <title>Credits</title> 18044 <para> 18045 Eric Blake 18046 </para> 18047 </sect2> 18048 </sect1> 18049 18050 <sect1 id="autocryptdoc"> 18051 <title>Autocrypt</title> 18052 18053 <para> 18054 NeoMutt can be compiled with Autocrypt support by running 18055 <literal>configure</literal> with the 18056 <literal>--autocrypt</literal> flag. Autocrypt provides 18057 easy to use, passive protection against data collection. Keys are 18058 distributed via an <literal>Autocrypt:</literal> header added to 18059 emails. It does <emphasis>not</emphasis> protect against active 18060 adversaries, and so should not be considered a substitute for 18061 normal encryption via your keyring, using key signing and the web 18062 of trust to verify identities. With an understanding of these 18063 limitations, Autocrypt still provides an easy way to minimize 18064 cleartext emails sent between common correspondents, without 18065 having to explicitly exchange keys. More information can be found 18066 at <ulink url="https://autocrypt.org/">https://autocrypt.org/</ulink>. 18067 </para> 18068 18069 <sect2 id="autocryptdoc-requirements"> 18070 <title>Requirements</title> 18071 <para> 18072 Autocrypt requires support for ECC cryptography, and NeoMutt by 18073 default will generate ECC keys. Therefore GnuPG 2.1 or greater 18074 is required. Additionally, NeoMutt's Autocrypt implementation uses 18075 GPGME and requires at least version 1.8.0. 18076 </para> 18077 <para> 18078 Account and peer information is stored in a sqlite3 database, and 18079 so NeoMutt must be configured with the <literal>--with-sqlite</literal> 18080 flag when autocrypt is enabled. 18081 </para> 18082 <para> 18083 It is highly recommended that NeoMutt be configured 18084 <literal>--with-idn</literal> or 18085 <literal>--with-idn2</literal> so that Autocrypt can properly 18086 deal with international domain names. 18087 </para> 18088 <para> 18089 While NeoMutt uses GPGME for Autocrypt, normal keyring operations 18090 can still be performed via classic mode (i.e. with 18091 <link linkend="crypt-use-gpgme">$crypt_use_gpgme</link> unset). 18092 However, to avoid unnecessary prompts, it is recommended gpg not 18093 be configured in <literal>loopback pinentry</literal> mode, and 18094 that <link linkend="pgp-use-gpg-agent">$pgp_use_gpg_agent</link> 18095 remain set (the default). 18096 </para> 18097 </sect2> 18098 18099 <sect2 id="autocryptdoc-init"> 18100 <title>First Run</title> 18101 <para> 18102 To enable Autocrypt, set <link 18103 linkend="autocrypt">$autocrypt</link>, and if desired change the 18104 value of <link linkend="autocrypt-dir">$autocrypt_dir</link> in 18105 your muttrc. The first time NeoMutt is run after that, you will be 18106 prompted to create 18107 <link linkend="autocrypt-dir">$autocrypt_dir</link>. NeoMutt will then 18108 automatically create an sqlite3 database and GPG keyring in that 18109 directory. Note since these files should be considered private, 18110 NeoMutt will create this directory with mode 18111 <literal>700</literal>. If you create the directory manually, 18112 you should do the same. 18113 </para> 18114 <para> 18115 NeoMutt recommends keeping the <link 18116 linkend="autocrypt-dir">$autocrypt_dir</link> directory set 18117 differently from your GnuPG keyring directory 18118 (e.g. <literal>~/.gnupg</literal>). Keys are automatically 18119 imported into the keyring from <literal>Autocrypt:</literal> 18120 headers. Compared to standard <quote>web of trust</quote> keys, 18121 Autocrypt keys are somewhat ephemeral, and the autocrypt 18122 database is used to track when keys change or fall out of use. 18123 Having these keys mixed in with your normal keyring will make it 18124 more difficult to use features such as 18125 <link linkend="crypt-opportunistic-encrypt">$crypt_opportunistic_encrypt</link> 18126 and Autocrypt at the same time. 18127 </para> 18128 <para> 18129 The <link linkend="autocrypt-dir">$autocrypt_dir</link> variable 18130 is not designed to be changed while NeoMutt is running. The 18131 database is created (if necessary) and connected to during 18132 startup. Changing the variable can result in a situation where 18133 NeoMutt is looking in one place for the database and a different 18134 place for the GPG keyring, resulting in strange behavior. 18135 </para> 18136 <para> 18137 Once the directory, keyring, and database are created, NeoMutt will 18138 ask whether you would like to create an account. In order to 18139 use Autocrypt, each sending address needs an account. As a 18140 convenience you can create an account during the first run. If 18141 you would like to add additional accounts later, this can be 18142 done via the <literal><autocrypt-acct-menu></literal> 18143 function in the index, by default bound to <literal>A</literal>. 18144 </para> 18145 <para> 18146 Account creation will first ask you for an email address. Next, 18147 it will ask whether you want to create a new key or select an 18148 existing key. (Note key selection takes place from the <link 18149 linkend="autocrypt-dir">$autocrypt_dir</link> keyring, which 18150 will normally be empty during first run). Finally, it will ask 18151 whether this address should prefer encryption or not. Autocrypt 18152 1.1 allows automatically enabling encryption if 18153 <emphasis>both</emphasis> sender and receiver have set 18154 <quote>prefer encryption</quote>. Otherwise, you will need to 18155 manually enable autocrypt encryption in the compose menu. For 18156 more details, see the compose menu section below. 18157 </para> 18158 <para> 18159 After optionally creating an account, NeoMutt will prompt you to 18160 scan mailboxes for Autocrypt headers. This step occurs because 18161 header cached messages are not re-scanned for Autocrypt headers. 18162 Scanning during this step will temporarily disable the header 18163 cache while opening each mailbox. If you wish to do this 18164 manually later, you can simulate the same thing by unsetting 18165 <link linkend="header-cache">$header_cache</link> and opening a 18166 mailbox. 18167 </para> 18168 <para> 18169 A final technical note: the first run process takes place 18170 between reading the muttrc and opening the initial mailbox. 18171 Some muttrc files will <link linkend="push">push</link> macros 18172 to be run after opening the mailbox. To prevent this from 18173 interfering with the first run prompts, NeoMutt disables all macros 18174 during the first run. 18175 </para> 18176 </sect2> 18177 18178 <sect2 id="autocryptdoc-compose"> 18179 <title>Compose Menu</title> 18180 <para> 18181 When enabled, Autocrypt will add a line to the compose menu with 18182 two fields: <literal>Autocrypt:</literal> and 18183 <literal>Recommendation:</literal>. 18184 </para> 18185 <para> 18186 The <literal>Autocrypt:</literal> field shows whether the 18187 message will be encrypted by Autocrypt when sent. It has two 18188 values: <literal>Encrypt</literal> and <literal>Off</literal>. 18189 <literal>Encrypt</literal> can be enabled using the 18190 <literal><autocrypt-menu></literal> function, by default 18191 bound to <literal>o</literal>. 18192 </para> 18193 <para> 18194 The <literal>Recommendation:</literal> field shows the output of 18195 the Autocrypt recommendation engine. This can have one of five 18196 values: 18197 </para> 18198 <itemizedlist> 18199 <listitem> 18200 <para> 18201 <literal>Off</literal> means the engine is disabled. This 18202 can happen if the From address doesn't have an autocrypt 18203 account, or if the account has been manually disabled. 18204 </para> 18205 </listitem> 18206 <listitem> 18207 <para> 18208 <literal>No</literal> means one or more recipients are 18209 missing an autocrypt key, or the key found is unusable 18210 (i.e. expired, revoked, disabled, invalid, or not usable for 18211 encryption.) 18212 </para> 18213 </listitem> 18214 <listitem> 18215 <para> 18216 <literal>Discouraged</literal> means a key was found for 18217 every recipient, but the engine is not confident the message 18218 will be decryptable by the recipient. This can happen if 18219 the key hasn't been used recently (compared to their last 18220 seen email). 18221 </para> 18222 <para> 18223 It can also happen if the key wasn't seen first-hand from 18224 the sender. Autocrypt has a feature where recipient keys 18225 can be included in group-encrypted emails. This allows you 18226 to reply to a conversation where you don't have a key 18227 first-hand from one of the other recipients. However, those 18228 keys are not trusted as much as from first-hand emails, so 18229 the engine warns you with a <literal>Discouraged</literal> 18230 status. 18231 </para> 18232 </listitem> 18233 <listitem> 18234 <para> 18235 <literal>Available</literal> means a key was found for every 18236 recipient, and the engine believes all keys are recent and 18237 seen from the recipient first hand. However, either you or 18238 one of the recipients chose not to specify <quote>prefer 18239 encryption</quote>. 18240 </para> 18241 </listitem> 18242 <listitem> 18243 <para> 18244 <literal>Yes</literal> is the same as 18245 <literal>Available</literal>, with the addition that you and 18246 all recipients have specified <quote>prefer encryption</quote>. 18247 This value will automatically enable 18248 encryption, unless you have manually switched it off or 18249 enabled regular encryption or signing via the 18250 <literal><pgp-menu></literal>. 18251 </para> 18252 </listitem> 18253 </itemizedlist> 18254 <para> 18255 As mentioned above the <literal><autocrypt-menu></literal> 18256 function, by default bound to <literal>o</literal>, can be used 18257 to change the <literal>Encrypt:</literal> field value. 18258 <literal>(e)ncrypt</literal> will toggle encryption on. 18259 <literal>(c)lear</literal> will toggle encryption off. If 18260 either of these are chosen, the field will remain in that state 18261 despite what the <literal>Recommendation:</literal> field shows. 18262 Lastly, <literal>(a)utomatic</literal> will set the value based 18263 on the recommendation engine's output. 18264 </para> 18265 <para> 18266 Autocrypt encryption defers to normal encryption or signing. 18267 <emphasis>Anything</emphasis> that enables normal encryption or 18268 signing will cause autocrypt encryption to turn off. The only 18269 exception is when replying to an autocrypt-encrypted email 18270 (i.e. an email decrypted from the <link 18271 linkend="autocrypt-dir">$autocrypt_dir</link> keyring). Then, 18272 if <link linkend="autocrypt-reply">$autocrypt_reply</link> is 18273 <emphasis>set</emphasis>, autocrypt mode will be forced on, 18274 overriding the settings 18275 <link linkend="crypt-auto-sign">$crypt_auto_sign</link>, 18276 <link linkend="crypt-auto-encrypt">$crypt_auto_encrypt</link>, 18277 <link linkend="crypt-reply-encrypt">$crypt_reply_encrypt</link>, 18278 <link linkend="crypt-reply-sign">$crypt_reply_sign</link>, 18279 <link linkend="crypt-reply-sign-encrypted">$crypt_reply_sign_encrypted</link>, and 18280 <link linkend="crypt-opportunistic-encrypt">$crypt_opportunistic_encrypt</link>. 18281 </para> 18282 <para> 18283 When postponing a message, autocrypt will respect 18284 <link linkend="postpone-encrypt">$postpone_encrypt</link>, but will 18285 use the autocrypt account key to encrypt the message. Be sure 18286 to set <link linkend="postpone-encrypt">$postpone_encrypt</link> 18287 to ensure postponed messages marked for autocrypt encryption are 18288 encrypted. 18289 </para> 18290 </sect2> 18291 18292 <sect2 id="autocryptdoc-acctmgmt"> 18293 <title>Account Management</title> 18294 <para> 18295 The Autocrypt Account Menu is available from the index via 18296 <literal><autocrypt-acct-menu></literal>, by default bound 18297 to <literal>A</literal>. See <link 18298 linkend="autocrypt-account-map">Autocrypt Account Menu</link> for the 18299 list of functions and their default keybindings. 18300 </para> 18301 <para> 18302 In this menu, you can create new accounts, delete accounts, 18303 toggle an account active/inactive, and toggle the <quote>prefer 18304 encryption</quote> flag for an account. 18305 </para> 18306 <para> 18307 Deleting an account only removes the account from the database. 18308 The GPG key is kept, to ensure you still have the ability to 18309 read past encrypted emails. 18310 </para> 18311 <para> 18312 The Autocrypt 1.1 <quote>Setup Message</quote> feature is not 18313 available yet, but will be added in the future. 18314 </para> 18315 </sect2> 18316 18317 <sect2 id="autocryptdoc-keyrings"> 18318 <title>Alternative Key and Keyring Strategies</title> 18319 <para> 18320 NeoMutt by default partitions Autocrypt from normal keyring 18321 encryption/signing. It does this by using a separate GPG 18322 keyring (in <link linkend="autocrypt-dir">$autocrypt_dir</link>) 18323 and creating a new ECC key in that keyring for accounts. There 18324 are good reasons for doing this by default. It keeps random 18325 keys found inside email headers out of your normal keyring. ECC 18326 keys are compact and better suited for email headers. Autocrypt 18327 key selection is completely different from <quote>web of 18328 trust</quote> key selection, based on last-seen rules as opposed 18329 to trust and validity. It also allows NeoMutt to distinguish 18330 Autocrypt encrypted emails from regular encrypted emails, and 18331 set the mode appropriately when replying to each type of email. 18332 </para> 18333 <para> 18334 Still, some users may want to use an existing key from their 18335 normal keyring for Autocrypt too. There are two ways this can 18336 be accomplished. The <emphasis>recommended</emphasis> way is to 18337 set <link linkend="autocrypt-dir">$autocrypt_dir</link> to your 18338 normal keyring directory (e.g. <literal>~/.gnupg</literal>). 18339 During account creation, choosing <quote>(s)elect existing GPG 18340 key</quote> will then list and allow selecting your existing key 18341 for the new account. 18342 </para> 18343 <para> 18344 An alternative is to copy your key over to the Autocrypt keyring, 18345 but there is a severe downside. NeoMutt <emphasis>first</emphasis> 18346 tries to decrypt messages using the Autocrypt keyring, and if 18347 that fails tries the normal keyring second. This means all 18348 encrypted emails to that key will be decrypted, and have 18349 signatures verified from, the Autocrypt keyring. Keys signatures 18350 and web of trust from your normal keyring will no longer show up 18351 in signatures when decrypting. 18352 </para> 18353 <para> 18354 For that reason, if you want to use an existing key from your 18355 normal keyring, it is recommended to just set <link 18356 linkend="autocrypt-dir">$autocrypt_dir</link> to 18357 <literal>~/.gnupg</literal>. This allows <quote>web of 18358 trust</quote> to show an appropriate signature message for 18359 verified messages. Autocrypt header keys will be imported into 18360 your keyring, but if you don't want them mixed you should 18361 strongly consider using a separate autocrypt key and keyring 18362 instead. 18363 </para> 18364 <para> 18365 Both methods have a couple additional caveats: 18366 </para> 18367 <itemizedlist> 18368 <listitem> 18369 <para> 18370 Replying to an Autocrypt decrypted message by default forces 18371 Autocrypt mode on. By sharing the same key, all replies 18372 will then start in Autocrypt mode, even if a message wasn't 18373 sent by one of your Autocrypt peers. <link 18374 linkend="autocrypt-reply">$autocrypt_reply</link> can be 18375 <emphasis>unset</emphasis> to allow manual control of the 18376 mode when replying. 18377 </para> 18378 </listitem> 18379 <listitem> 18380 <para> 18381 When NeoMutt creates an account from a GPG key, it exports the 18382 public key, base64 encodes it, and stores that value in the 18383 sqlite3 database. The value is then used in the Autocrypt 18384 header added to outgoing emails. The ECC keys NeoMutt creates 18385 don't change, but if you use external keys that expire, when 18386 you resign to extend the expiration you will need to 18387 recreate the Autocrypt account using the <link 18388 linkend="autocryptdoc-acctmgmt">account menu</link>. 18389 Otherwise the Autocrypt header will contain the old expired 18390 exported keydata. 18391 </para> 18392 </listitem> 18393 </itemizedlist> 18394 </sect2> 18395 </sect1> 18396 </chapter> 18397 18398 <chapter id="security"> 18399 <title>Security Considerations</title> 18400 <para> 18401 First of all, NeoMutt contains no security holes included by intention 18402 but may contain unknown security holes. As a consequence, please run 18403 NeoMutt only with as few permissions as possible. Especially, do not run 18404 NeoMutt as the super user. 18405 </para> 18406 <para> 18407 When configuring NeoMutt, there're some points to note about secure 18408 setups so please read this chapter carefully. 18409 </para> 18410 18411 <sect1 id="security-passwords"> 18412 <title>Passwords</title> 18413 <para> 18414 Although NeoMutt can be told the various passwords for accounts, please 18415 never store passwords in configuration files. Besides the fact that the 18416 system's operator can always read them, you could forget to mask it out 18417 when reporting a bug or asking for help via a mailing list. Even worse, 18418 your mail including your password could be archived by internet search 18419 engines, mail-to-news gateways etc. It may already be too late before 18420 you notice your mistake. 18421 </para> 18422 </sect1> 18423 18424 <sect1 id="security-tempfiles"> 18425 <title>Temporary Files</title> 18426 <para> 18427 NeoMutt uses many temporary files for viewing messages, verifying 18428 digital signatures, etc. As long as being used, these files are visible 18429 by other users and maybe even readable in case of misconfiguration. 18430 Also, a different location for these files may be desired which can be 18431 changed via the <link linkend="tmpdir">$tmpdir</link> variable. 18432 </para> 18433 </sect1> 18434 18435 <sect1 id="security-leaks"> 18436 <title>Information Leaks</title> 18437 18438 <sect2 id="security-leaks-mid"> 18439 <title>Message-Id: headers</title> 18440 <para> 18441 Message-Id: headers contain a local part that is to be created in 18442 a unique fashion. In order to do so, NeoMutt will <quote>leak</quote> 18443 some information to the outside world when sending messages: the 18444 generation of this header includes a step counter which is increased 18445 (and rotated) with every message sent. Other parts include the date, 18446 time, PID of NeoMutt, and <link linkend="hostname">$hostname</link>. 18447 In a longer running NeoMutt session, others can 18448 make assumptions about your mailing habits 18449 depending on the number of messages sent. If this is not desired, the 18450 header can be manually provided using 18451 <link linkend="edit-headers">$edit_headers</link> (though not 18452 recommended). 18453 </para> 18454 </sect2> 18455 18456 <sect2 id="security-leaks-mailto"> 18457 <title><literal>mailto:</literal>-style Links</title> 18458 <para> 18459 As NeoMutt be can be set up to be the mail client to handle 18460 <literal>mailto:</literal> style links in websites, there're security 18461 considerations, too. Arbitrary header fields can be embedded in these 18462 links which could override existing header fields or attach arbitrary 18463 files using 18464 <link linkend="attach-header">the Attach: pseudoheader</link>. This 18465 may be problematic if the 18466 <link linkend="edit-headers">$edit-headers</link> variable is 18467 <emphasis>unset</emphasis>, i.e. the user doesn't want to see header 18468 fields while editing the message and doesn't pay enough attention to 18469 the compose menu's listing of attachments. 18470 </para> 18471 <para> 18472 For example, following a link like 18473 </para> 18474 <screen>mailto:joe@host?Attach=~/.gnupg/secring.gpg</screen> 18475 <para> 18476 will send out the user's private gnupg keyring to 18477 <literal>joe@host</literal> if the user doesn't follow the 18478 information on screen carefully enough. 18479 </para> 18480 <para> 18481 To prevent these issues, NeoMutt by default only accepts the 18482 <literal>Subject</literal> and <literal>Body</literal> headers. 18483 Allowed headers can be adjusted with the 18484 <link linkend="mailto-allow"><command>mailto_allow</command></link> 18485 and 18486 <link linkend="mailto-allow"><command>unmailto_allow</command></link> 18487 commands. 18488 </para> 18489 </sect2> 18490 </sect1> 18491 18492 <sect1 id="security-external"> 18493 <title>External Applications</title> 18494 <para> 18495 NeoMutt in many places has to rely on external applications or for 18496 convenience supports mechanisms involving external applications. 18497 </para> 18498 <para> 18499 One of these is the <literal>mailcap</literal> mechanism as defined by 18500 RFC1524. Details about a secure use of the mailcap mechanisms is given 18501 in <xref linkend="secure-mailcap" />. 18502 </para> 18503 <para> 18504 Besides the mailcap mechanism, NeoMutt uses a number of other external 18505 utilities for operation, for example to provide crypto support, in 18506 backtick expansion in configuration files or format string filters. The 18507 same security considerations apply for these as for tools involved via 18508 mailcap. 18509 </para> 18510 </sect1> 18511 </chapter> 18512 18513 <chapter id="tuning"> 18514 <title>Performance Tuning</title> 18515 18516 <sect1 id="tuning-mailboxes"> 18517 <title>Reading and Writing Mailboxes</title> 18518 <para> 18519 NeoMutt's performance when reading mailboxes can be improved in two 18520 ways: 18521 </para> 18522 <orderedlist> 18523 <listitem> 18524 <para> 18525 For remote folders (IMAP and POP) as well as folders using 18526 one-file-per message storage (Maildir and MH), NeoMutt's 18527 performance can be greatly improved using 18528 <link linkend="header-caching">header caching</link>. using 18529 a single database per folder. 18530 </para> 18531 </listitem> 18532 <listitem> 18533 <para> 18534 NeoMutt provides the <link linkend="read-inc">$read_inc</link> and 18535 <link linkend="write-inc">$write_inc</link> variables to specify at 18536 which rate to update progress counters. If these values are too 18537 low, NeoMutt may spend more time on updating the progress counter 18538 than it spends on actually reading/writing folders. 18539 </para> 18540 <para> 18541 For example, when opening a maildir folder with a few thousand 18542 messages, the default value for 18543 <link linkend="read-inc">$read_inc</link> may be too low. It can be 18544 tuned on on a folder-basis using 18545 <link linkend="folder-hook"><command>folder-hook</command>s</link>: 18546 </para> 18547 18548<screen> 18549<emphasis role="comment"># use very high $read_inc to speed up reading hcache'd maildirs</emphasis> 18550folder-hook . 'set read_inc=1000' 18551<emphasis role="comment"># use lower value for reading slower remote IMAP folders</emphasis> 18552folder-hook ^imap 'set read_inc=100' 18553<emphasis role="comment"># use even lower value for reading even slower remote POP folders</emphasis> 18554folder-hook ^pop 'set read_inc=1' 18555</screen> 18556 18557 </listitem> 18558 </orderedlist> 18559 <para> 18560 These settings work on a per-message basis. However, as messages may 18561 greatly differ in size and certain operations are much faster than 18562 others, even per-folder settings of the increment variables may not be 18563 desirable as they produce either too few or too much progress updates. 18564 Thus, NeoMutt allows to limit the number of progress updates per second 18565 it'll actually send to the terminal using the 18566 <link linkend="time-inc">$time_inc</link> variable. 18567 </para> 18568 </sect1> 18569 18570 <sect1 id="tuning-messages"> 18571 <title>Reading Messages from Remote Folders</title> 18572 <para> 18573 Reading messages from remote folders such as IMAP an POP can be slow 18574 especially for large mailboxes since NeoMutt only caches a very limited 18575 number of recently viewed messages (usually 10) per session (so that it 18576 will be gone for the next session.) 18577 </para> 18578 <para> 18579 To improve performance and permanently cache whole messages and 18580 headers, please refer to <link linkend="body-caching">body caching</link> 18581 and <link linkend="header-caching">header caching</link> for details. 18582 </para> 18583 <para> 18584 Additionally, it may be worth trying some of NeoMutt's experimental 18585 features. <link linkend="imap-qresync">$imap_qresync</link> (which 18586 requires header caching) can provide a huge speed boost opening 18587 mailboxes if your IMAP server supports it. 18588 <link linkend="imap-deflate">$imap_deflate</link> enables compression, 18589 which can also noticeably reduce download time for large mailboxes and 18590 messages. 18591 </para> 18592 </sect1> 18593 18594 <sect1 id="tuning-search"> 18595 <title>Searching and Limiting</title> 18596 <para> 18597 When searching mailboxes either via a search or a limit action, for 18598 some patterns NeoMutt distinguishes between regular expression and 18599 string searches. For regular expressions, patterns are prefixed with 18600 <quote>~</quote> and with <quote>=</quote> for string searches. 18601 </para> 18602 <para> 18603 Even though a regular expression search is fast, it's several times 18604 slower than a pure string search which is noticeable especially on 18605 large folders. As a consequence, a string search should be used instead 18606 of a regular expression search if the user already knows enough about 18607 the search pattern. 18608 </para> 18609 <para> 18610 For example, when limiting a large folder to all messages sent to or by 18611 an author, it's much faster to search for the initial part of an e-mail 18612 address via <literal>=Luser@</literal> instead of 18613 <literal>~Luser@</literal>. This is especially true for searching 18614 message bodies since a larger amount of input has to be searched. 18615 </para> 18616 <para> 18617 As for regular expressions, a lower case string search pattern makes 18618 NeoMutt perform a case-insensitive search except for IMAP (because for 18619 IMAP NeoMutt performs server-side searches which don't support 18620 case-insensitivity). 18621 </para> 18622 </sect1> 18623 </chapter> 18624 18625 <chapter id="reference"> 18626 <title>Reference</title> 18627 18628 <sect1 id="commandline"> 18629 <title>Command-Line Options</title> 18630 <para> 18631 Running <literal>neomutt</literal> with no arguments will make NeoMutt 18632 attempt to read your spool mailbox. However, it is possible to read 18633 other mailboxes and to send messages from the command line as well. 18634 </para> 18635 18636 <table id="tab-commandline-options"> 18637 <title>Command line options</title> 18638 <tgroup cols="2"> 18639 <thead> 18640 <row> 18641 <entry>Option</entry> 18642 <entry>Description</entry> 18643 </row> 18644 </thead> 18645 <tbody> 18646 <row> 18647 <entry>--</entry> 18648 <entry> 18649 Special argument forces NeoMutt to stop option parsing and 18650 treat remaining arguments as <literal>address</literal>es even 18651 if they start with a dash 18652 </entry> 18653 </row> 18654 <row> 18655 <entry>-A <literal>alias</literal></entry> 18656 <entry> 18657 Print an expanded version of the given <literal>alias</literal> 18658 to stdout and exit 18659 </entry> 18660 </row> 18661 <row> 18662 <entry>-a <literal>file</literal></entry> 18663 <entry> 18664 Attach one or more <literal>file</literal>s to a message (must 18665 be the last option). Add any addresses after the 18666 '<emphasis role="bold">--</emphasis>' argument, e.g.: 18667 18668<screen> 18669neomutt -a image.jpg -- address1 18670neomutt -a image.jpg *.png -- address1 address2 18671</screen> 18672 18673 </entry> 18674 </row> 18675 <row> 18676 <entry>-B</entry> 18677 <entry> 18678 Run in batch mode (do not start the ncurses UI) 18679 </entry> 18680 </row> 18681 <row> 18682 <entry>-b <literal>address</literal></entry> 18683 <entry> 18684 Specify a blind carbon copy (Bcc) recipient 18685 </entry> 18686 </row> 18687 <row> 18688 <entry>-c <literal>address</literal></entry> 18689 <entry> 18690 Specify a carbon copy (Cc) recipient 18691 </entry> 18692 </row> 18693 <row> 18694 <entry>-D</entry> 18695 <entry> 18696 Dump all config variables as 18697 '<emphasis role="bold">name=value</emphasis>' pairs 18698 to stdout 18699 </entry> 18700 </row> 18701 <row> 18702 <entry>-D -O</entry> 18703 <entry> 18704 Like <emphasis role="bold">-D</emphasis>, but show one-liner documentation 18705 </entry> 18706 </row> 18707 <row> 18708 <entry>-D -S</entry> 18709 <entry> 18710 Like <emphasis role="bold">-D</emphasis>, but hide the value of 18711 sensitive variables 18712 </entry> 18713 </row> 18714 <row> 18715 <entry>-d <literal>level</literal></entry> 18716 <entry> 18717 Log debugging output to a file (default is 18718 "<literal>~/.neomuttdebug0</literal>"). 18719 The <literal>level</literal> can range from 1–5 and 18720 affects verbosity (a value of 2 is recommended). Using this 18721 option along with <emphasis role="bold">-l</emphasis> is useful 18722 to log the early startup process (before reading any 18723 configuration and hence 18724 <link linkend="debug-level">$debug_level</link> and 18725 <link linkend="debug-file">$debug_file</link>) 18726 </entry> 18727 </row> 18728 <row> 18729 <entry>-E</entry> 18730 <entry> 18731 Edit 18732 <literal>draft</literal> (<emphasis role="bold">-H</emphasis>) or 18733 <literal>include</literal> (<emphasis role="bold">-i</emphasis>) 18734 file during message composition 18735 </entry> 18736 </row> 18737 <row> 18738 <entry>-e <literal>command</literal></entry> 18739 <entry> 18740 Specify a <literal>command</literal> to be run after reading 18741 the config files 18742 </entry> 18743 </row> 18744 <row> 18745 <entry>-F <literal>config</literal></entry> 18746 <entry> 18747 Specify an alternative initialization file to read, see section 18748 <link linkend="configuration-files">Location of Initialization Files</link> 18749 for a list of regular configuration files 18750 </entry> 18751 </row> 18752 <row> 18753 <entry>-f <literal>mailbox</literal></entry> 18754 <entry> 18755 Specify a <literal>mailbox</literal> (as defined with 18756 <link linkend="mailboxes"><command>mailboxes</command> command</link>) 18757 to load 18758 </entry> 18759 </row> 18760 <row> 18761 <entry>-G</entry> 18762 <entry> 18763 Start NeoMutt with a listing of subscribed newsgroups 18764 </entry> 18765 </row> 18766 <row> 18767 <entry>-g <literal>server</literal></entry> 18768 <entry> 18769 Like <emphasis role="bold">-G</emphasis>, but start at 18770 specified news <literal>server</literal> 18771 </entry> 18772 </row> 18773 <row> 18774 <entry>-H <literal>draft</literal></entry> 18775 <entry> 18776 Specify a <literal>draft</literal> file with header and body 18777 for message composing 18778 </entry> 18779 </row> 18780 <row> 18781 <entry>-h</entry> 18782 <entry> 18783 Print this help message and exit 18784 </entry> 18785 </row> 18786 <row> 18787 <entry>-i <literal>include</literal></entry> 18788 <entry> 18789 Specify an <literal>include</literal> file to be embedded in 18790 the body of a message 18791 </entry> 18792 </row> 18793 <row> 18794 <entry>-l <literal>file</literal></entry> 18795 <entry> 18796 Specify a <literal>file</literal> for debugging output (default 18797 "<literal>~/.neomuttdebug0</literal>"). This 18798 overrules <link linkend="debug-file">$debug_file</link> 18799 setting and NeoMutt keeps up to five debug logs ({ 18800 <literal>file</literal> | 18801 <link linkend="debug-file">$debug_file</link> | 18802 <literal>~/.neomuttdebug</literal> }[<literal>0-4</literal>]) 18803 before override the oldest file 18804 </entry> 18805 </row> 18806 <row> 18807 <entry>-m <literal>type</literal></entry> 18808 <entry> 18809 Specify a default mailbox format <literal>type</literal> for 18810 newly created folders. The <literal>type</literal> is either 18811 MH, MMDF, Maildir or mbox (case-insensitive) 18812 </entry> 18813 </row> 18814 <row> 18815 <entry>-n</entry> 18816 <entry> 18817 Do not read the system-wide configuration file 18818 </entry> 18819 </row> 18820 <row> 18821 <entry>-p</entry> 18822 <entry> 18823 Resume a prior postponed message, if any 18824 </entry> 18825 </row> 18826 <row> 18827 <entry>-Q <literal>variable</literal></entry> 18828 <entry> 18829 Query a configuration <literal>variable</literal> and print its 18830 value to stdout (after the config has been read and any 18831 commands executed). Adding <literal>-O</literal> will display 18832 one-liner documentation. 18833 </entry> 18834 </row> 18835 <row> 18836 <entry>-R</entry> 18837 <entry> 18838 Open mailbox in read-only mode 18839 </entry> 18840 </row> 18841 <row> 18842 <entry>-s <literal>subject</literal></entry> 18843 <entry> 18844 Specify a <literal>subject</literal> (must be enclosed in 18845 quotes if it has spaces) 18846 </entry> 18847 </row> 18848 <row> 18849 <entry>-v</entry> 18850 <entry> 18851 Print the NeoMutt version and compile-time definitions and exit 18852 </entry> 18853 </row> 18854 <row> 18855 <entry>-vv</entry> 18856 <entry> 18857 Print the NeoMutt license and copyright information and exit 18858 </entry> 18859 </row> 18860 <row> 18861 <entry>-y</entry> 18862 <entry> 18863 Start NeoMutt with a listing of all defined mailboxes 18864 </entry> 18865 </row> 18866 <row> 18867 <entry>-Z</entry> 18868 <entry> 18869 Open the first mailbox with new message or exit immediately 18870 with exit code 1 if none is found in all defined mailboxes 18871 </entry> 18872 </row> 18873 <row> 18874 <entry>-z</entry> 18875 <entry> 18876 Open the first or specified 18877 (<emphasis role="bold">-f</emphasis>) mailbox if it holds any 18878 message or exit immediately with exit code 1 otherwise 18879 </entry> 18880 </row> 18881 </tbody> 18882 </tgroup> 18883 </table> 18884 <para> 18885 To read messages in a mailbox or exit immediately 18886 </para> 18887 <cmdsynopsis> 18888 <command>neomutt</command> 18889 <arg choice="opt"> 18890 <option>-nz</option> 18891 </arg> 18892 <arg choice="opt"> 18893 <option>-F</option> 18894 <replaceable>config</replaceable> 18895 </arg> 18896 <arg choice="opt"> 18897 <option>-m</option> 18898 <replaceable>type</replaceable> 18899 </arg> 18900 <arg choice="opt"> 18901 <option>-f</option> 18902 <replaceable>mailbox</replaceable> 18903 </arg> 18904 </cmdsynopsis> 18905 <para> 18906 To compose a new message 18907 </para> 18908 <cmdsynopsis> 18909 <command>neomutt</command> 18910 <arg choice="opt"> 18911 <option>-Enx</option> 18912 </arg> 18913 <arg choice="opt"> 18914 <option>-F</option> 18915 <replaceable>config</replaceable> 18916 </arg> 18917 <arg choice="opt"> 18918 <option>-b</option> 18919 <replaceable>address</replaceable> 18920 </arg> 18921 <arg choice="opt"> 18922 <option>-c</option> 18923 <replaceable>address</replaceable> 18924 </arg> 18925 <arg choice="opt"> 18926 <option>-H</option> 18927 <replaceable>draft</replaceable> 18928 </arg> 18929 <arg choice="opt"> 18930 <option>-i</option> 18931 <replaceable>include</replaceable> 18932 </arg> 18933 <arg choice="opt"> 18934 <option>-s</option> 18935 <replaceable>subject</replaceable> 18936 </arg> 18937 <arg choice="opt"> 18938 <option>-a</option> 18939 <replaceable>file</replaceable> 18940 <arg choice="opt" rep="repeat" /> 18941 <option>--</option> 18942 </arg> 18943 <group choice="req" rep="repeat"> 18944 <arg choice="plain"> 18945 <replaceable>address</replaceable> 18946 </arg> 18947 <arg choice="plain"> 18948 <replaceable>mailto_url</replaceable> 18949 </arg> 18950 </group> 18951 </cmdsynopsis> 18952 <para> 18953 NeoMutt also supports a <quote>batch</quote> mode to send prepared 18954 messages. Simply redirect input from the file you wish to send. For 18955 example, 18956 </para> 18957 18958<screen> 18959neomutt -s "data set for run #2" professor@bigschool.edu < ~/run2.dat 18960</screen> 18961 18962 <para> 18963 will send a message to 18964 <literal><professor@bigschool.edu></literal> with a subject of 18965 <quote>data set for run #2</quote>. In the body of the message will be 18966 the contents of the file <quote>~/run2.dat</quote>. 18967 </para> 18968 <para> 18969 An include file passed with <literal>-i</literal> will be used as the 18970 body of the message. When combined with <literal>-E</literal>, the 18971 include file will be directly edited during message composition. The 18972 file will be modified regardless of whether the message is sent or 18973 aborted. 18974 </para> 18975 <para> 18976 A draft file passed with <literal>-H</literal> will be used as the 18977 initial header and body for the message. Multipart messages can be used 18978 as a draft file. When combined with <literal>-E</literal>, the draft 18979 file will be updated to the final state of the message after 18980 composition, regardless of whether the message is sent, aborted, or 18981 even postponed. Note that if the message is sent encrypted or signed, 18982 the draft file will be saved that way too. 18983 </para> 18984 <para> 18985 All files passed with <literal>-a</literal> <emphasis>file</emphasis> 18986 will be attached as a MIME part to the message. To attach a single or 18987 several files, use <literal>--</literal> to separate files and 18988 recipient addresses: 18989 </para> 18990 <screen>neomutt -a image.png -- some@one.org</screen> 18991 <para> 18992 or 18993 </para> 18994 <screen>neomutt -a *.png -- some@one.org</screen> 18995 <note> 18996 <para> 18997 The <literal>-a</literal> option must be last in the option list. 18998 </para> 18999 </note> 19000 <para> 19001 In addition to accepting a list of email addresses, NeoMutt also 19002 accepts a URL with the <literal>mailto:</literal> schema as specified 19003 in RFC2368. This is useful when configuring a web browser to launch 19004 NeoMutt when clicking on mailto links. 19005 </para> 19006 19007<screen> 19008neomutt mailto:some@one.org?subject=test&cc=other@one.org 19009</screen> 19010 19011 </sect1> 19012 19013 <sect1 id="commands"> 19014 <title>Configuration Commands</title> 19015 <para> 19016 The following are the commands understood by NeoMutt: 19017 </para> 19018 <itemizedlist> 19019 <listitem> 19020 <cmdsynopsis> 19021 <command> 19022 <link linkend="account-hook">account-hook</link> 19023 </command> 19024 <arg choice="plain"> 19025 <replaceable>regex</replaceable> 19026 <replaceable>command</replaceable> 19027 </arg> 19028 </cmdsynopsis> 19029 </listitem> 19030 <listitem> 19031 <cmdsynopsis> 19032 <command> 19033 <link linkend="alias">alias</link> 19034 </command> 19035 <arg choice="opt" rep="repeat"> 19036 <option>-group</option> 19037 <replaceable class="parameter">name</replaceable> 19038 </arg> 19039 <arg choice="plain"> 19040 <replaceable class="parameter">key</replaceable> 19041 </arg> 19042 <arg choice="plain"> 19043 <replaceable class="parameter">address</replaceable> 19044 </arg> 19045 <arg choice="opt" rep="repeat"> 19046 <replaceable class="parameter">, address</replaceable> 19047 </arg> 19048 <command> 19049 <link linkend="alias">unalias</link> 19050 </command> 19051 <arg choice="opt" rep="repeat"> 19052 <option>-group</option> 19053 <replaceable>name</replaceable> 19054 </arg> 19055 <group choice="req"> 19056 <arg choice="plain"> 19057 <replaceable class="parameter">*</replaceable> 19058 </arg> 19059 <arg choice="plain" rep="repeat"> 19060 <replaceable class="parameter">key</replaceable> 19061 </arg> 19062 </group> 19063 </cmdsynopsis> 19064 </listitem> 19065 <listitem> 19066 <cmdsynopsis> 19067 <command> 19068 <link linkend="alternates">alternates</link> 19069 </command> 19070 <arg choice="opt" rep="repeat"> 19071 <option>-group</option> 19072 <replaceable>name</replaceable> 19073 </arg> 19074 <arg choice="plain"> 19075 <replaceable>regex</replaceable> 19076 </arg> 19077 <arg choice="opt" rep="repeat"> 19078 <replaceable>regex</replaceable> 19079 </arg> 19080 <command> 19081 <link linkend="alternates">unalternates</link> 19082 </command> 19083 <arg choice="opt" rep="repeat"> 19084 <option>-group</option> 19085 <replaceable>name</replaceable> 19086 </arg> 19087 <group choice="req"> 19088 <arg choice="plain"> 19089 <replaceable>*</replaceable> 19090 </arg> 19091 <arg choice="plain" rep="repeat"> 19092 <replaceable>regex</replaceable> 19093 </arg> 19094 </group> 19095 </cmdsynopsis> 19096 </listitem> 19097 <listitem> 19098 <cmdsynopsis> 19099 <command> 19100 <link linkend="alternative-order">alternative_order</link> 19101 </command> 19102 <arg choice="plain"> 19103 <replaceable>mime-type</replaceable> 19104 </arg> 19105 <arg choice="opt"> 19106 <replaceable>/mime-subtype</replaceable> 19107 </arg> 19108 <arg choice="opt" rep="repeat"> 19109 <arg choice="plain"> 19110 <replaceable>mime-type</replaceable> 19111 </arg> 19112 <arg choice="opt"> 19113 <replaceable>/mime-subtype</replaceable> 19114 </arg> 19115 </arg> 19116 <command> 19117 <link linkend="alternative-order">unalternative_order</link> 19118 </command> 19119 <group choice="req"> 19120 <arg choice="plain">*</arg> 19121 <arg choice="opt" rep="repeat"> 19122 <arg choice="plain"> 19123 <replaceable>mime-type</replaceable> 19124 </arg> 19125 <arg choice="opt"> 19126 <replaceable>/mime-subtype</replaceable> 19127 </arg> 19128 </arg> 19129 </group> 19130 </cmdsynopsis> 19131 </listitem> 19132 <listitem> 19133 <cmdsynopsis> 19134 <command> 19135 <link linkend="attachments">attachments</link> 19136 </command> 19137 <group choice="req"> 19138 <arg choice="plain">+</arg> 19139 <arg choice="plain">-</arg> 19140 </group> 19141 <arg choice="plain"> 19142 <replaceable>disposition</replaceable> 19143 </arg> 19144 <arg choice="plain"> 19145 <replaceable>mime-type</replaceable> 19146 </arg> 19147 <command> 19148 <link linkend="attachments">unattachments</link> 19149 </command> 19150 <group choice="req"> 19151 <arg choice="plain">+</arg> 19152 <arg choice="plain">-</arg> 19153 </group> 19154 <arg choice="plain"> 19155 <replaceable>disposition</replaceable> 19156 </arg> 19157 <arg choice="plain"> 19158 <replaceable>mime-type</replaceable> 19159 </arg> 19160 <command> 19161 <link linkend="attachments">attachments</link> 19162 </command> 19163 <arg choice="plain"> 19164 <option>?</option> 19165 </arg> 19166 <command> 19167 <link linkend="attachments">unattachments</link> 19168 </command> 19169 <arg choice="plain"> 19170 <option>*</option> 19171 </arg> 19172 </cmdsynopsis> 19173 </listitem> 19174 <listitem> 19175 <cmdsynopsis> 19176 <command> 19177 <link linkend="auto-view">auto_view</link> 19178 </command> 19179 <arg choice="plain"> 19180 <replaceable>mime-type</replaceable> 19181 </arg> 19182 <arg choice="opt"> 19183 <replaceable>/mime-subtype</replaceable> 19184 </arg> 19185 <arg choice="opt" rep="repeat"> 19186 <arg choice="plain"> 19187 <replaceable>mime-type</replaceable> 19188 </arg> 19189 <arg choice="opt"> 19190 <replaceable>/mime-subtype</replaceable> 19191 </arg> 19192 </arg> 19193 <command> 19194 <link linkend="auto-view">unauto_view</link> 19195 </command> 19196 <group choice="req"> 19197 <arg choice="plain">*</arg> 19198 <arg choice="opt" rep="repeat"> 19199 <arg choice="plain"> 19200 <replaceable>mime-type</replaceable> 19201 </arg> 19202 <arg choice="opt"> 19203 <replaceable>/mime-subtype</replaceable> 19204 </arg> 19205 </arg> 19206 </group> 19207 </cmdsynopsis> 19208 </listitem> 19209 <listitem> 19210 <cmdsynopsis> 19211 <command> 19212 <link linkend="bind">bind</link> 19213 </command> 19214 <arg choice="plain"> 19215 <replaceable class="parameter">map</replaceable> 19216 </arg> 19217 <arg choice="opt" rep="repeat"> 19218 <replaceable class="parameter">,map</replaceable> 19219 </arg> 19220 <arg choice="plain"> 19221 <replaceable class="parameter">key</replaceable> 19222 </arg> 19223 <arg choice="plain"> 19224 <replaceable class="parameter">function</replaceable> 19225 </arg> 19226 </cmdsynopsis> 19227 </listitem> 19228 <listitem> 19229 <cmdsynopsis> 19230 <command><link linkend="cd">cd</link></command> 19231 <arg choice="plain"> 19232 <replaceable class="parameter">directory</replaceable> 19233 </arg> 19234 </cmdsynopsis> 19235 </listitem> 19236 <listitem> 19237 <cmdsynopsis> 19238 <command> 19239 <link linkend="charset-hook">charset-hook</link> 19240 </command> 19241 <arg choice="plain"> 19242 <replaceable class="parameter">alias</replaceable> 19243 </arg> 19244 <arg choice="plain"> 19245 <replaceable class="parameter">charset</replaceable> 19246 </arg> 19247 <command> 19248 <link linkend="charset-hook">iconv-hook</link> 19249 </command> 19250 <arg choice="plain"> 19251 <replaceable class="parameter">charset</replaceable> 19252 </arg> 19253 <arg choice="plain"> 19254 <replaceable class="parameter">local-charset</replaceable> 19255 </arg> 19256 </cmdsynopsis> 19257 </listitem> 19258 <listitem> 19259 <cmdsynopsis> 19260 <command> 19261 <link linkend="color">color</link> 19262 </command> 19263 <arg choice="plain"> 19264 <replaceable class="parameter">object</replaceable> 19265 </arg> 19266 <arg choice="opt" rep="repeat"> 19267 <replaceable class="parameter">attribute</replaceable> 19268 </arg> 19269 <arg choice="plain"> 19270 <replaceable class="parameter">foreground</replaceable> 19271 </arg> 19272 <arg choice="plain"> 19273 <replaceable class="parameter">background</replaceable> 19274 </arg> 19275 <command> 19276 <link linkend="color">color</link> 19277 </command> 19278 <group choice="req"> 19279 <arg choice="plain"> 19280 <option>header</option> 19281 </arg> 19282 <arg choice="plain"> 19283 <option>body</option> 19284 </arg> 19285 </group> 19286 <arg choice="opt" rep="repeat"> 19287 <replaceable class="parameter">attribute</replaceable> 19288 </arg> 19289 <arg choice="plain"> 19290 <replaceable class="parameter">foreground</replaceable> 19291 </arg> 19292 <arg choice="plain"> 19293 <replaceable class="parameter">background</replaceable> 19294 </arg> 19295 <arg choice="plain"> 19296 <replaceable class="parameter">regex</replaceable> 19297 </arg> 19298 <command> 19299 <link linkend="color">color</link> 19300 </command> 19301 <arg choice="plain"> 19302 <option>index</option> 19303 </arg> 19304 <arg choice="opt" rep="repeat"> 19305 <replaceable class="parameter">attribute</replaceable> 19306 </arg> 19307 <arg choice="plain"> 19308 <replaceable class="parameter">foreground</replaceable> 19309 </arg> 19310 <arg choice="plain"> 19311 <replaceable class="parameter">background</replaceable> 19312 </arg> 19313 <arg choice="plain"> 19314 <replaceable class="parameter">pattern</replaceable> 19315 </arg> 19316 <command> 19317 <link linkend="color">uncolor</link> 19318 </command> 19319 <group choice="req"> 19320 <arg choice="plain"> 19321 <option>index</option> 19322 </arg> 19323 <arg choice="plain"> 19324 <option>header</option> 19325 </arg> 19326 <arg choice="plain"> 19327 <option>body</option> 19328 </arg> 19329 </group> 19330 <group choice="req"> 19331 <arg choice="plain"> 19332 <replaceable>*</replaceable> 19333 </arg> 19334 <arg choice="plain" rep="repeat"> 19335 <replaceable>pattern</replaceable> 19336 </arg> 19337 </group> 19338 </cmdsynopsis> 19339 </listitem> 19340 <listitem> 19341 <cmdsynopsis> 19342 <command> 19343 <link linkend="crypt-hook">crypt-hook</link> 19344 </command> 19345 <arg choice="plain"> 19346 <replaceable class="parameter">regex</replaceable> 19347 </arg> 19348 <arg choice="plain"> 19349 <replaceable class="parameter">keyid</replaceable> 19350 </arg> 19351 </cmdsynopsis> 19352 </listitem> 19353 <listitem> 19354 <cmdsynopsis> 19355 <command> 19356 <link linkend="exec">exec</link> 19357 </command> 19358 <arg choice="plain"> 19359 <replaceable class="parameter">function</replaceable> 19360 </arg> 19361 <arg choice="opt" rep="repeat"> 19362 <replaceable class="parameter">function</replaceable> 19363 </arg> 19364 </cmdsynopsis> 19365 </listitem> 19366 <listitem> 19367 <cmdsynopsis> 19368 <command> 19369 <link linkend="default-save-mailbox">fcc-save-hook</link> 19370 </command> 19371 <arg choice="plain"> 19372 <replaceable class="parameter">pattern</replaceable> 19373 </arg> 19374 <arg choice="plain"> 19375 <replaceable class="parameter">mailbox</replaceable> 19376 </arg> 19377 <command> 19378 <link linkend="default-save-mailbox">fcc-hook</link> 19379 </command> 19380 <arg choice="plain"> 19381 <replaceable class="parameter">pattern</replaceable> 19382 </arg> 19383 <arg choice="plain"> 19384 <replaceable class="parameter">mailbox</replaceable> 19385 </arg> 19386 <command> 19387 <link linkend="default-save-mailbox">save-hook</link> 19388 </command> 19389 <arg choice="plain"> 19390 <replaceable class="parameter">pattern</replaceable> 19391 </arg> 19392 <arg choice="plain"> 19393 <replaceable class="parameter">mailbox</replaceable> 19394 </arg> 19395 </cmdsynopsis> 19396 </listitem> 19397 <listitem> 19398 <cmdsynopsis> 19399 <command> 19400 <link linkend="folder-hook">folder-hook</link> 19401 </command> 19402 <arg choice="plain"> 19403 <replaceable class="parameter">regex</replaceable> 19404 </arg> 19405 <arg choice="plain"> 19406 <replaceable class="parameter">command</replaceable> 19407 </arg> 19408 </cmdsynopsis> 19409 </listitem> 19410 <listitem> 19411 <cmdsynopsis> 19412 <command> 19413 <link linkend="addrgroup">group</link> 19414 </command> 19415 <arg choice="opt" rep="repeat"> 19416 <option>-group</option> 19417 <replaceable class="parameter">name</replaceable> 19418 </arg> 19419 <group choice="req"> 19420 <arg choice="plain" rep="repeat"> 19421 <option>-rx</option> 19422 <replaceable class="parameter">expr</replaceable> 19423 </arg> 19424 <arg choice="plain" rep="repeat"> 19425 <option>-addr</option> 19426 <replaceable class="parameter">expr</replaceable> 19427 </arg> 19428 </group> 19429 <command> 19430 <link linkend="addrgroup">ungroup</link> 19431 </command> 19432 <arg choice="opt" rep="repeat"> 19433 <option>-group</option> 19434 <replaceable class="parameter">name</replaceable> 19435 </arg> 19436 <group choice="req"> 19437 <arg choice="plain"> 19438 <replaceable class="parameter">*</replaceable> 19439 </arg> 19440 <arg choice="plain" rep="repeat"> 19441 <option>-rx</option> 19442 <replaceable class="parameter">expr</replaceable> 19443 </arg> 19444 <arg choice="plain" rep="repeat"> 19445 <option>-addr</option> 19446 <replaceable class="parameter">expr</replaceable> 19447 </arg> 19448 </group> 19449 </cmdsynopsis> 19450 </listitem> 19451 <listitem> 19452 <cmdsynopsis> 19453 <command> 19454 <link linkend="hdr-order">hdr_order</link> 19455 </command> 19456 <arg choice="plain"> 19457 <replaceable class="parameter">header</replaceable> 19458 </arg> 19459 <arg choice="opt" rep="repeat"> 19460 <replaceable class="parameter">header</replaceable> 19461 </arg> 19462 <command> 19463 <link linkend="hdr-order">unhdr_order</link> 19464 </command> 19465 <group choice="req"> 19466 <arg choice="plain"> 19467 <replaceable>*</replaceable> 19468 </arg> 19469 <arg choice="plain" rep="repeat"> 19470 <replaceable>header</replaceable> 19471 </arg> 19472 </group> 19473 </cmdsynopsis> 19474 </listitem> 19475 <listitem> 19476 <cmdsynopsis> 19477 <command> 19478 <link linkend="ifdef">ifdef</link> 19479 </command> 19480 <arg choice="plain"> 19481 <replaceable class="parameter">symbol</replaceable> 19482 </arg> 19483 <arg choice="plain"> 19484 <replaceable class="parameter">"config-command [args...]"</replaceable> 19485 </arg> 19486 <command> 19487 <link linkend="ifdef">ifndef</link> 19488 </command> 19489 <arg choice="plain"> 19490 <replaceable class="parameter">symbol</replaceable> 19491 </arg> 19492 <arg choice="plain"> 19493 <replaceable class="parameter">"config-command [args...]"</replaceable> 19494 </arg> 19495 <command> 19496 <link linkend="ifdef">finish</link> 19497 </command> 19498 </cmdsynopsis> 19499 </listitem> 19500 <listitem> 19501 <cmdsynopsis> 19502 <command> 19503 <link linkend="ignore">ignore</link> 19504 </command> 19505 <arg choice="plain"> 19506 <replaceable class="parameter">pattern</replaceable> 19507 </arg> 19508 <arg choice="opt" rep="repeat"> 19509 <replaceable class="parameter">pattern</replaceable> 19510 </arg> 19511 <command> 19512 <link linkend="ignore">unignore</link> 19513 </command> 19514 <group choice="req"> 19515 <arg choice="plain"> 19516 <replaceable>*</replaceable> 19517 </arg> 19518 <arg choice="plain" rep="repeat"> 19519 <replaceable>pattern</replaceable> 19520 </arg> 19521 </group> 19522 </cmdsynopsis> 19523 </listitem> 19524 <listitem> 19525 <cmdsynopsis> 19526 <command> 19527 <link linkend="index-format-hook">index-format-hook</link> 19528 </command> 19529 <arg choice="plain"> 19530 <replaceable class="parameter">name</replaceable> 19531 </arg> 19532 <arg choice="plain"> 19533 <replaceable class="parameter">[!]pattern</replaceable> 19534 </arg> 19535 <arg choice="plain"> 19536 <replaceable class="parameter">format-string</replaceable> 19537 </arg> 19538 </cmdsynopsis> 19539 </listitem> 19540 <listitem> 19541 <cmdsynopsis> 19542 <command> 19543 <link linkend="lists">lists</link> 19544 </command> 19545 <arg> 19546 <option>-group</option> 19547 <replaceable class="parameter">name</replaceable> 19548 </arg> 19549 <arg choice="plain"> 19550 <replaceable class="parameter">regex</replaceable> 19551 </arg> 19552 <arg choice="opt" rep="repeat"> 19553 <replaceable class="parameter">regex</replaceable> 19554 </arg> 19555 <command> 19556 <link linkend="lists">unlists</link> 19557 </command> 19558 <arg choice="opt" rep="repeat"> 19559 <option>-group</option> 19560 <replaceable>name</replaceable> 19561 </arg> 19562 <group choice="req"> 19563 <arg choice="plain"> 19564 <replaceable>*</replaceable> 19565 </arg> 19566 <arg choice="plain" rep="repeat"> 19567 <replaceable>regex</replaceable> 19568 </arg> 19569 </group> 19570 <command> 19571 <link linkend="lists">subscribe</link> 19572 </command> 19573 <arg choice="opt" rep="repeat"> 19574 <option>-group</option> 19575 <replaceable class="parameter">name</replaceable> 19576 </arg> 19577 <arg choice="plain"> 19578 <replaceable class="parameter">regex</replaceable> 19579 </arg> 19580 <arg choice="opt" rep="repeat"> 19581 <replaceable class="parameter">regex</replaceable> 19582 </arg> 19583 <command> 19584 <link linkend="lists">unsubscribe</link> 19585 </command> 19586 <arg choice="opt" rep="repeat"> 19587 <option>-group</option> 19588 <replaceable>name</replaceable> 19589 </arg> 19590 <group choice="req"> 19591 <arg choice="plain"> 19592 <replaceable class="parameter">*</replaceable> 19593 </arg> 19594 <arg choice="plain" rep="repeat"> 19595 <replaceable class="parameter">regex</replaceable> 19596 </arg> 19597 </group> 19598 </cmdsynopsis> 19599 </listitem> 19600 <listitem> 19601 <cmdsynopsis> 19602 <command> 19603 <link linkend="macro">macro</link> 19604 </command> 19605 <arg choice="plain"> 19606 <replaceable class="parameter">menu</replaceable> 19607 </arg> 19608 <arg choice="opt" rep="repeat"> 19609 <replaceable class="parameter">,menu</replaceable> 19610 </arg> 19611 <arg choice="plain"> 19612 <replaceable class="parameter">key</replaceable> 19613 </arg> 19614 <arg choice="plain"> 19615 <replaceable class="parameter">sequence</replaceable> 19616 </arg> 19617 <arg choice="opt"> 19618 <replaceable class="parameter">description</replaceable> 19619 </arg> 19620 </cmdsynopsis> 19621 </listitem> 19622 <listitem> 19623 <cmdsynopsis> 19624 <command> 19625 <link linkend="mailboxes">mailboxes</link> 19626 </command> 19627 <arg choice="plain"> 19628 <replaceable class="parameter">mailbox</replaceable> 19629 </arg> 19630 <arg choice="opt" rep="repeat"> 19631 <replaceable class="parameter">mailbox</replaceable> 19632 </arg> 19633 <command> 19634 <link linkend="mailboxes">named-mailboxes</link> 19635 </command> 19636 <arg choice="plain"> 19637 <replaceable class="parameter">description</replaceable> 19638 </arg> 19639 <arg choice="plain"> 19640 <replaceable class="parameter">mailbox</replaceable> 19641 </arg> 19642 <group choice="opt" rep="repeat"> 19643 <arg choice="plain"> 19644 <replaceable class="parameter">description mailbox</replaceable> 19645 </arg> 19646 </group> 19647 <command> 19648 <link linkend="mailboxes">unmailboxes</link> 19649 </command> 19650 <group choice="req"> 19651 <arg choice="plain"> 19652 <replaceable class="parameter">*</replaceable> 19653 </arg> 19654 <arg choice="plain" rep="repeat"> 19655 <replaceable class="parameter">mailbox</replaceable> 19656 </arg> 19657 </group> 19658 </cmdsynopsis> 19659 </listitem> 19660 <listitem> 19661 <cmdsynopsis> 19662 <command> 19663 <link linkend="mailto-allow">mailto_allow</link> 19664 </command> 19665 <group choice="req"> 19666 <arg choice="plain"> 19667 <replaceable class="parameter">*</replaceable> 19668 </arg> 19669 <arg choice="plain" rep="repeat"> 19670 <replaceable class="parameter">header-field</replaceable> 19671 </arg> 19672 </group> 19673 <command> 19674 <link linkend="mailto-allow">unmailto_allow</link> 19675 </command> 19676 <group choice="req"> 19677 <arg choice="plain"> 19678 <replaceable class="parameter">*</replaceable> 19679 </arg> 19680 <arg choice="plain" rep="repeat"> 19681 <replaceable class="parameter">header-field</replaceable> 19682 </arg> 19683 </group> 19684 </cmdsynopsis> 19685 </listitem> 19686 <listitem> 19687 <cmdsynopsis> 19688 <command> 19689 <link linkend="mbox-hook">mbox-hook</link> 19690 </command> 19691 <arg choice="plain"> 19692 <replaceable class="parameter">regex</replaceable> 19693 </arg> 19694 <arg choice="plain"> 19695 <replaceable class="parameter">mailbox</replaceable> 19696 </arg> 19697 </cmdsynopsis> 19698 </listitem> 19699 <listitem> 19700 <cmdsynopsis> 19701 <command> 19702 <link linkend="message-hook">message-hook</link> 19703 </command> 19704 <arg choice="plain"> 19705 <replaceable class="parameter">pattern</replaceable> 19706 </arg> 19707 <arg choice="plain"> 19708 <replaceable class="parameter">command</replaceable> 19709 </arg> 19710 </cmdsynopsis> 19711 </listitem> 19712 <listitem> 19713 <cmdsynopsis> 19714 <command> 19715 <link linkend="mime-lookup">mime_lookup</link> 19716 </command> 19717 <arg choice="plain"> 19718 <replaceable>mime-type</replaceable> 19719 </arg> 19720 <arg choice="opt"> 19721 <replaceable>/mime-subtype</replaceable> 19722 </arg> 19723 <arg choice="opt" rep="repeat"> 19724 <arg choice="plain"> 19725 <replaceable>mime-type</replaceable> 19726 </arg> 19727 <arg choice="opt"> 19728 <replaceable>/mime-subtype</replaceable> 19729 </arg> 19730 </arg> 19731 <command> 19732 <link linkend="mime-lookup">unmime_lookup</link> 19733 </command> 19734 <group choice="req"> 19735 <arg choice="plain">*</arg> 19736 <arg choice="opt" rep="repeat"> 19737 <arg choice="plain"> 19738 <replaceable>mime-type</replaceable> 19739 </arg> 19740 <arg choice="opt"> 19741 <replaceable>/mime-subtype</replaceable> 19742 </arg> 19743 </arg> 19744 </group> 19745 </cmdsynopsis> 19746 </listitem> 19747 <listitem> 19748 <cmdsynopsis> 19749 <command> 19750 <link linkend="color-mono">mono</link> 19751 </command> 19752 <arg choice="plain"> 19753 <replaceable class="parameter">object</replaceable> 19754 </arg> 19755 <arg choice="plain"> 19756 <replaceable class="parameter">attribute</replaceable> 19757 </arg> 19758 <command> 19759 <link linkend="color-mono">mono</link> 19760 </command> 19761 <group choice="req"> 19762 <arg choice="plain"> 19763 <option>header</option> 19764 </arg> 19765 <arg choice="plain"> 19766 <option>body</option> 19767 </arg> 19768 </group> 19769 <arg choice="plain"> 19770 <replaceable class="parameter">attribute</replaceable> 19771 </arg> 19772 <arg choice="plain"> 19773 <replaceable class="parameter">regex</replaceable> 19774 </arg> 19775 <command> 19776 <link linkend="color-mono">mono</link> 19777 </command> 19778 <arg choice="plain"> 19779 <option>index-object</option> 19780 </arg> 19781 <arg choice="plain"> 19782 <replaceable class="parameter">attribute</replaceable> 19783 </arg> 19784 <arg choice="plain"> 19785 <replaceable class="parameter">pattern</replaceable> 19786 </arg> 19787 <command> 19788 <link linkend="color-mono">unmono</link> 19789 </command> 19790 <group choice="req"> 19791 <arg choice="plain"> 19792 <option>index-object</option> 19793 </arg> 19794 <arg choice="plain"> 19795 <option>header</option> 19796 </arg> 19797 <arg choice="plain"> 19798 <option>body</option> 19799 </arg> 19800 </group> 19801 <group choice="req"> 19802 <arg choice="plain"> 19803 <replaceable class="parameter">*</replaceable> 19804 </arg> 19805 <arg choice="plain" rep="repeat"> 19806 <replaceable class="parameter">pattern</replaceable> 19807 </arg> 19808 </group> 19809 </cmdsynopsis> 19810 </listitem> 19811 <listitem> 19812 <cmdsynopsis> 19813 <command> 19814 <link linkend="my-hdr">my_hdr</link> 19815 </command> 19816 <arg choice="plain"> 19817 <replaceable class="parameter">string</replaceable> 19818 </arg> 19819 <command> 19820 <link linkend="my-hdr">unmy_hdr</link> 19821 </command> 19822 <group choice="req"> 19823 <arg choice="plain"> 19824 <replaceable class="parameter">*</replaceable> 19825 </arg> 19826 <arg choice="plain" rep="repeat"> 19827 <replaceable class="parameter">field</replaceable> 19828 </arg> 19829 </group> 19830 </cmdsynopsis> 19831 </listitem> 19832 <listitem> 19833 <cmdsynopsis> 19834 <command> 19835 <link linkend="open-hook">open-hook</link> 19836 </command> 19837 <arg choice="plain"> 19838 <replaceable class="parameter">regex</replaceable> 19839 </arg> 19840 <arg choice="plain"> 19841 <replaceable class="parameter">"shell-command"</replaceable> 19842 </arg> 19843 <command> 19844 <link linkend="close-hook">close-hook</link> 19845 </command> 19846 <arg choice="plain"> 19847 <replaceable class="parameter">regex</replaceable> 19848 </arg> 19849 <arg choice="plain"> 19850 <replaceable class="parameter">"shell-command"</replaceable> 19851 </arg> 19852 <command> 19853 <link linkend="append-hook">append-hook</link> 19854 </command> 19855 <arg choice="plain"> 19856 <replaceable class="parameter">regex</replaceable> 19857 </arg> 19858 <arg choice="plain"> 19859 <replaceable class="parameter">"shell-command"</replaceable> 19860 </arg> 19861 </cmdsynopsis> 19862 </listitem> 19863 <listitem> 19864 <cmdsynopsis> 19865 <command> 19866 <link linkend="push">push</link> 19867 </command> 19868 <arg choice="plain"> 19869 <replaceable class="parameter">string</replaceable> 19870 </arg> 19871 </cmdsynopsis> 19872 </listitem> 19873 <listitem> 19874 <cmdsynopsis> 19875 <command> 19876 <link linkend="send-hook">reply-hook</link> 19877 </command> 19878 <arg choice="plain"> 19879 <replaceable class="parameter">pattern</replaceable> 19880 </arg> 19881 <arg choice="plain"> 19882 <replaceable class="parameter">command</replaceable> 19883 </arg> 19884 <command> 19885 <link linkend="send-hook">send-hook</link> 19886 </command> 19887 <arg choice="plain"> 19888 <replaceable class="parameter">pattern</replaceable> 19889 </arg> 19890 <arg choice="plain"> 19891 <replaceable class="parameter">command</replaceable> 19892 </arg> 19893 <command> 19894 <link linkend="send-hook">send2-hook</link> 19895 </command> 19896 <arg choice="plain"> 19897 <replaceable class="parameter">pattern</replaceable> 19898 </arg> 19899 <arg choice="plain"> 19900 <replaceable class="parameter">command</replaceable> 19901 </arg> 19902 </cmdsynopsis> 19903 </listitem> 19904 <listitem> 19905 <cmdsynopsis> 19906 <command> 19907 <link linkend="score-command">score</link> 19908 </command> 19909 <arg choice="plain"> 19910 <replaceable class="parameter">pattern</replaceable> 19911 </arg> 19912 <arg choice="plain"> 19913 <replaceable class="parameter">value</replaceable> 19914 </arg> 19915 <command> 19916 <link linkend="score-command">unscore</link> 19917 </command> 19918 <group choice="req"> 19919 <arg choice="plain"> 19920 <replaceable class="parameter">*</replaceable> 19921 </arg> 19922 <arg choice="plain" rep="repeat"> 19923 <replaceable class="parameter">pattern</replaceable> 19924 </arg> 19925 </group> 19926 </cmdsynopsis> 19927 </listitem> 19928 <listitem> 19929 <cmdsynopsis> 19930 <command> 19931 <link linkend="set">set</link> 19932 </command> 19933 <group choice="req"> 19934 <arg choice="plain"> 19935 <group choice="opt"> 19936 <arg choice="plain"> 19937 <option>no</option> 19938 </arg> 19939 <arg choice="plain"> 19940 <option>inv</option> 19941 </arg> 19942 <arg choice="plain"> 19943 <option>&</option> 19944 </arg> 19945 <arg choice="plain"> 19946 <option>?</option> 19947 </arg> 19948 </group> 19949 <replaceable class="parameter">variable</replaceable> 19950 </arg> 19951 <arg choice="plain"> 19952 <replaceable class="parameter">variable=value</replaceable> 19953 </arg> 19954 </group> 19955 <arg choice="opt" rep="repeat"></arg> 19956 <command> 19957 <link linkend="set">unset</link> 19958 </command> 19959 <arg choice="plain"> 19960 <replaceable class="parameter">variable</replaceable> 19961 </arg> 19962 <arg choice="opt" rep="repeat"> 19963 <replaceable class="parameter">variable</replaceable> 19964 </arg> 19965 <command> 19966 <link linkend="set">reset</link> 19967 </command> 19968 <arg choice="plain"> 19969 <replaceable class="parameter">variable</replaceable> 19970 </arg> 19971 <arg choice="opt" rep="repeat"> 19972 <replaceable class="parameter">variable</replaceable> 19973 </arg> 19974 <command> 19975 <link linkend="set">toggle</link> 19976 </command> 19977 <arg choice="plain"> 19978 <replaceable class="parameter">variable</replaceable> 19979 </arg> 19980 <arg choice="opt" rep="repeat"> 19981 <replaceable class="parameter">variable</replaceable> 19982 </arg> 19983 </cmdsynopsis> 19984 </listitem> 19985 <listitem> 19986 <cmdsynopsis> 19987 <command> 19988 <link linkend="setenv">setenv</link> 19989 </command> 19990 <group choice="req"> 19991 <arg choice="plain"> 19992 <replaceable class="parameter">?variable</replaceable> 19993 </arg> 19994 <arg choice="plain"> 19995 <replaceable class="parameter">variable value</replaceable> 19996 </arg> 19997 </group> 19998 <command> 19999 <link linkend="setenv">unsetenv</link> 20000 </command> 20001 <arg choice="plain"> 20002 <replaceable class="parameter">variable</replaceable> 20003 </arg> 20004 </cmdsynopsis> 20005 </listitem> 20006 <listitem> 20007 <cmdsynopsis> 20008 <command> 20009 <link linkend="sidebar-whitelist">sidebar_whitelist</link> 20010 </command> 20011 <arg choice="plain"> 20012 <replaceable class="parameter">mailbox</replaceable> 20013 </arg> 20014 <arg choice="opt" rep="repeat"> 20015 <replaceable class="parameter">mailbox</replaceable> 20016 </arg> 20017 <command> 20018 <link linkend="sidebar-whitelist">unsidebar_whitelist</link> 20019 </command> 20020 <group choice="req"> 20021 <arg choice="plain"> 20022 <replaceable class="parameter">*</replaceable> 20023 </arg> 20024 <arg choice="plain" rep="repeat"> 20025 <replaceable class="parameter">mailbox</replaceable> 20026 </arg> 20027 </group> 20028 </cmdsynopsis> 20029 </listitem> 20030 <listitem> 20031 <cmdsynopsis> 20032 <command> 20033 <link linkend="source">source</link> 20034 </command> 20035 <arg choice="plain"> 20036 <replaceable class="parameter">filename</replaceable> 20037 </arg> 20038 </cmdsynopsis> 20039 </listitem> 20040 <listitem> 20041 <cmdsynopsis> 20042 <command> 20043 <link linkend="spam">spam</link> 20044 </command> 20045 <arg choice="plain"> 20046 <replaceable class="parameter">pattern</replaceable> 20047 </arg> 20048 <arg choice="plain"> 20049 <replaceable class="parameter">format</replaceable> 20050 </arg> 20051 <command> 20052 <link linkend="spam">nospam</link> 20053 </command> 20054 <group choice="req"> 20055 <arg choice="plain"> 20056 <replaceable class="parameter">*</replaceable> 20057 </arg> 20058 <arg choice="plain"> 20059 <replaceable class="parameter">pattern</replaceable> 20060 </arg> 20061 </group> 20062 </cmdsynopsis> 20063 </listitem> 20064 <listitem> 20065 <cmdsynopsis> 20066 <command> 20067 <link linkend="display-munging">subjectrx</link> 20068 </command> 20069 <arg choice="plain"> 20070 <replaceable class="parameter">pattern</replaceable> 20071 </arg> 20072 <arg choice="plain"> 20073 <replaceable class="parameter">replacement</replaceable> 20074 </arg> 20075 <command> 20076 <link linkend="display-munging">unsubjectrx</link> 20077 </command> 20078 <group choice="req"> 20079 <arg choice="plain"> 20080 <replaceable class="parameter">*</replaceable> 20081 </arg> 20082 <arg choice="plain"> 20083 <replaceable class="parameter">pattern</replaceable> 20084 </arg> 20085 </group> 20086 </cmdsynopsis> 20087 </listitem> 20088 <listitem> 20089 <cmdsynopsis> 20090 <command> 20091 <link linkend="global-hooks">timeout-hook</link> 20092 </command> 20093 <arg choice="plain"> 20094 <replaceable class="parameter">command</replaceable> 20095 </arg> 20096 <command> 20097 <link linkend="global-hooks">startup-hook</link> 20098 </command> 20099 <arg choice="plain"> 20100 <replaceable class="parameter">command</replaceable> 20101 </arg> 20102 <command> 20103 <link linkend="global-hooks">shutdown-hook</link> 20104 </command> 20105 <arg choice="plain"> 20106 <replaceable class="parameter">command</replaceable> 20107 </arg> 20108 </cmdsynopsis> 20109 </listitem> 20110 <listitem> 20111 <cmdsynopsis> 20112 <command> 20113 <link linkend="unhook">unhook</link> 20114 </command> 20115 <group choice="req"> 20116 <arg choice="plain"> 20117 <replaceable class="parameter">*</replaceable> 20118 </arg> 20119 <arg choice="plain"> 20120 <replaceable class="parameter">hook-type</replaceable> 20121 </arg> 20122 </group> 20123 </cmdsynopsis> 20124 </listitem> 20125 </itemizedlist> 20126 </sect1> 20127 20128 <sect1 id="variables"> 20129 <title>Configuration Variables</title> 20130
