From b1f9e85f14ffe85e536c76f2355297aad350a96f Mon Sep 17 00:00:00 2001 From: Rocco Rutte Date: Tue, 31 Mar 2009 12:58:15 +0200 Subject: [PATCH] Manual: Lots of minor improvements (markup consistency, wording) --- ChangeLog | 14 + doc/manual.xml.head | 745 +++++++++++++++++++++++--------------------- 2 files changed, 409 insertions(+), 350 deletions(-) diff --git a/ChangeLog b/ChangeLog index 73cb77da..68e1cf5e 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,17 @@ +2009-03-30 14:58 +0200 Rocco Rutte (318748f3962b) + + * doc/manual.xml.head: For mailbox formats, add some more verbose pros + and cons + +2009-03-30 13:18 +0200 Rocco Rutte (63e458e83e5b) + + * doc/manual.xml.head: Manual: Add section about zeroprinting format + strings to format string section + +2009-03-28 22:37 +0100 Thomas Roessler (be9fb07730c6) + + * ChangeLog, mutt_idna.c: Make IDNA code more readable + 2009-03-28 16:11 +0100 Rocco Rutte (77cfe8016930) * doc/manual.xml.head: Manual: Add section roughly explaining config diff --git a/doc/manual.xml.head b/doc/manual.xml.head index e4fcca8f..9428ca34 100644 --- a/doc/manual.xml.head +++ b/doc/manual.xml.head @@ -189,6 +189,7 @@ conventions for special terms. <create-alias>named Mutt function ˆGControl+G key combination $mail_checkMutt configuration option +$HOMEenvironment variable @@ -285,6 +286,13 @@ informational and error messages as well as for prompts and for entering interactive commands. + +Mutt is configured through variables which, if the user wants to +permanently use a non-default value, are written to configuration +files. Mutt supports a rich config file syntax to make even complex +configuration files readable and commentable. + + Because Mutt allows for customizing almost all key bindings, there are so-called functions which can be executed manually (using the @@ -416,7 +424,9 @@ variable and can be made persistent using an external file specified using $history_file. You may cycle through them at an editor prompt by using the <history-up> and/or -<history-down> commands. +<history-down> commands. But notice that Mutt +does not remember the currently entered text, it only cycles through +history and wraps around at the end or beginning. @@ -434,7 +444,7 @@ following categories: -Mutt automatically filters out repeated items from the history. It +Mutt automatically filters out consecutively repeated items from the history. It also mimics the behavior of some shells by ignoring items starting with a space. The latter feature can be useful in macros to not clobber the history's valuable entries with unwanted entries. @@ -449,8 +459,8 @@ the history's valuable entries with unwanted entries. Similar to many other mail clients, there are two modes in which mail is -read in Mutt. The first is the index of messages in the mailbox, which is -called the index in Mutt. The second mode is the display of the +read in Mutt. The first is a list of messages in the mailbox, which is +called the index menu in Mutt. The second mode is the display of the message contents. This is called the pager. @@ -569,9 +579,11 @@ who the message is addressed to. They can be customized with the The Pager -By default, Mutt uses its builtin pager to display the contents of messages. -The pager is very similar to the Unix program less though not nearly as -featureful. +By default, Mutt uses its builtin pager to display the contents of +messages (an external pager such as less(1) can be +configured, see $pager variable). +The pager is very similar to the Unix program less(1) +though not nearly as featureful. @@ -686,9 +698,8 @@ your xterm, then that color will be used instead of green. Note that the search commands in the pager take regular expressions, which are not quite the same as the more complex patterns used by the search -command in the index. This is because the pager only performs simple -text search, whereas the index provides boolean filtering on several -aspects of messages. +command in the index. This is because patterns are used to select messages by +criteria whereas the pager already displays a selected message. @@ -698,9 +709,18 @@ aspects of messages. Threaded Mode -When the mailbox is sorted by threads, there are -a few additional functions available in the index and pager modes -as shown in . +So-called threads provide a hierarchy of messages where +replies are linked to their parent message(s). This organizational form +is extremely useful in mailing lists where different parts of the +discussion diverge. Mutt displays threads as a tree structure. + + + +In Mutt, when a mailbox is sorted +by threads, there are a few additional functions +available in the index +and pager modes as shown in +.
@@ -728,19 +748,23 @@ as shown in .
- Collapsing a thread displays only the first message in the thread and hides the others. This is useful when threads contain so many messages that you can only see a handful of threads on the screen. See %M in $index_format. For example, you could use "%?M?(#%03M)&(%4l)?" in $index_format to optionally -display the number of hidden messages if the thread is collapsed. +display the number of hidden messages if the thread is +collapsed. The %?<char>?<if-part>&<else-part>? +syntax is explained in detail in +format string conditionals. - -See also: $strict_threads. +Technically, every reply should contain a list of its parent messages in +the thread tree, but not all do. In these cases, Mutt groups them by +subject which can be controlled using the +$strict_threads variable. @@ -1005,7 +1029,7 @@ The bindings shown in are available in the Bouncing a message sends the message as-is to the recipient you specify. Forwarding a message allows you to add comments or modify the message you are forwarding. These items are discussed -in greater detail in the next chapter Forwarding +in greater detail in the next section Forwarding and Bouncing Mail. @@ -1013,14 +1037,16 @@ and Bouncing Mail. Mutt will then enter the compose menu and prompt you for the recipients to place on the To: header field. Next, it will ask you for the Subject: field for the message, providing a default if -you are replying to or forwarding a message. See also +you are replying to or forwarding a message. You again +have the chance to adjust recipients, subject, and security settings +right before actually sending the message. See also $askcc, $askbcc, $autoedit, $bounce, $fast_reply, and $include -for changing how Mutt asks these questions. +for changing how and if Mutt asks these questions. @@ -1100,7 +1126,7 @@ a A to indicate that you are in attach-message mode. When editing the header because of $edit_headers being set, there are a several pseudo headers available which -will not be included in sent messages. +will not be included in sent messages but trigger special Mutt behavior. @@ -1108,9 +1134,13 @@ will not be included in sent messages. If you specify + + Fcc: filename + + as a header, Mutt will pick up filename just as if you had used the <edit-fcc> function in the compose menu. @@ -1122,9 +1152,14 @@ just as if you had used the <edit-fcc> function in the You can also attach files to your message by specifying + -Attach: filename [ description ] + +Attach: filename +[ description ] + + where filename is the file to attach and description is an optional string to use as the description of the attached file. Spaces in filenames have to be escaped using backslash (\). @@ -1412,7 +1447,7 @@ message's body (surrounded by indicating lines) or including it as a MIME attachment, depending on the value of the $mime_forward variable. Decoding of attachments, like in the pager, can be controlled by the $forward_decode and $mime_forward_decode variables, respectively. The desired forwarding format may depend on the content, -therefore $mime_forward is a quadoption which, for +therefore $mime_forward is a quadoption which, for example, can be set to ask-no. @@ -1523,7 +1558,7 @@ set realname='Mutt user' ; ignore x- The hash mark, or pound sign (#), is used as a comment character. You can use it to annotate your initialization file. All text after the comment character -to the end of the line is ignored. For example, +to the end of the line is ignored. @@ -1541,11 +1576,11 @@ namely that a single quote is used to specify a literal string (one that is not interpreted for shell variables or quoting with a backslash [see next paragraph]), while double quotes indicate a string for which should be evaluated. For example, backticks are evaluated inside of double -quotes, but not for single quotes. +quotes, but not for single quotes. -\ quotes the next character, just as in shells such as bash and zsh. +\ quotes the next character, just as in shells such as bash and zsh. For example, if want to put quotes " inside of a string, you can use \ to force the next character to be a literal instead of interpreted character. @@ -1565,15 +1600,30 @@ carriage-return, respectively. -A \ at the end of a line can be used to split commands over -multiple lines, provided that the split points don't appear in the -middle of command names. +A \ at the end of a line can be used to split commands over +multiple lines as it escapes the line end, provided that the split points don't appear in the +middle of command names. Lines are first concatenated before +interpretation so that a multi-line can be commented by commenting out +the first line only. + +Splitting long configuration commands over several lines + +set status_format="some very \ +long value split \ +over several lines" + + + It is also possible to substitute the output of a Unix command in an initialization file. This is accomplished by enclosing the command in -backticks (``). For example, +backticks (``). In , the output of the +Unix command uname -a will be substituted before the +line is parsed. +Since initialization files are line oriented, only +the first line of output from the Unix command will be substituted. @@ -1583,18 +1633,6 @@ my_hdr X-Operating-System: `uname -a` - -The output of the Unix command uname -a will be substituted before the -line is parsed. - - - - -Since initialization files are line oriented, only -the first line of output from the Unix command will be substituted. - - - Both environment variables and mutt variables can be accessed by prepending $ to the name of the variable. For example, @@ -1609,7 +1647,7 @@ set record=+sent_on_$HOSTNAME will cause mutt to save outgoing messages to a folder named -sent_on_kremvax if the environment variable HOSTNAME is set to +sent_on_kremvax if the environment variable $HOSTNAME is set to kremvax. (See $record for details.) @@ -1633,7 +1671,8 @@ which doesn't have a default value since it's determined by Mutt at startup. If a configuration file is not encoded in the same character set the $config_charset variable should be used: all lines starting with the next are recoded -from $config_charset to $charset. +from $config_charset +to $charset. @@ -1644,10 +1683,11 @@ following implications: These variables should be set early in a configuration -file with $charset preceding $config_charset so Mutt -know what character set to convert to. +file with $charset preceding +$config_charset so Mutt +knows what character set to convert to. -If $config_charset is set, it should be set +If $config_charset is set, it should be set in each configuration file because the value is global and not per configuration file. @@ -1770,7 +1810,7 @@ a short string to a full address. If you want to create an alias for more than -one address, you must separate the addresses with a comma (,). +one address, you must separate the addresses with a comma (,). @@ -1820,10 +1860,6 @@ in the sense that Mutt will happily append aliases to any file, but in order for the new aliases to take effect you need to explicitly source this file too. - -For example: - - Configuring external alias files @@ -1844,7 +1880,7 @@ also enter aliases in your editor at the appropriate headers if you have the In addition, at the various address prompts, you can use the tab character to expand a partial alias to the full alias. If there are multiple matches, mutt will bring up a menu with the matching aliases. In order to be -presented with the full list of aliases, you must hit tab with out a partial +presented with the full list of aliases, you must hit tab without a partial alias, such as at the beginning of the prompt or after a comma denoting multiple addresses. @@ -2145,18 +2181,19 @@ logical not operator for the expression. Settings are not restored when you leave the mailbox. For example, a command action to perform is to change the sorting method based upon the mailbox being read: - - -folder-hook mutt set sort=threads - +folder-hook mutt set sort=threads - However, the sorting method is not restored to its previous value when reading a different mailbox. To specify a default command, use the pattern . before other folder-hooks adjusting a value on a per-folder basis -because folder-hooks are evaluated in the order given in the configuration file. +because folder-hooks are evaluated in the order given in the +configuration file. + + + + The following example will set the sort variable to date-sent for all folders but to threads for all folders containing mutt in their name. @@ -2230,7 +2267,7 @@ than one user (e.g., the system Muttrc). Optionally you can specify a descriptive text after sequence, -which is shown in the help screens. +which is shown in the help screens if they contain a description. @@ -2315,7 +2352,7 @@ silently truncated at the screen width, and are not wrapped. If your terminal supports color, you can spice up Mutt by creating your own color scheme. To define the color of an object (type of information), you -must specify both a foreground color and a background color (it is not +must specify both a foreground color and a background color (it is not possible to only specify one or the other). @@ -2339,7 +2376,7 @@ in the header/body of a message, index matches pa message (informational messages) normal quoted (text matching $quote_regexp in the body of a message) -quoted1, quoted2, ..., quotedN (higher levels of quoting) +quoted1, quoted2, ..., quotedN (higher levels of quoting) search (hiliting of words in the pager) signaturestatus (mode lines used to display info about the mailbox or message) tilde (the ˜ used to pad blank lines in the pager) @@ -2394,7 +2431,7 @@ setting this variable. The uncolor command can be applied to the index object only. It -removes entries from the list. You must specify the same pattern +removes entries from the list. You must specify the same pattern specified in the color command for it to be removed. The pattern * is a special token which means to clear the color index list of all entries. @@ -2402,20 +2439,18 @@ a special token which means to clear the color index list of all entries. Mutt also recognizes the keywords color0, color1, …, -colorN-1 (N being the number of colors supported +colorN-1 (N being the number of colors supported by your terminal). This is useful when you remap the colors for your display (for example by changing the color associated with color2 for your xterm), since color names may then lose their normal meaning. + If your terminal does not support color, it is still possible change the video -attributes through the use of the mono command: +attributes through the use of the mono command. Usage: - -Usage: - mono @@ -2487,9 +2522,12 @@ can be one of the following: - + Message header display + +Selecting Headers + Usage: @@ -2536,10 +2574,6 @@ For example, if you do ignore x- it is possible to unignor unignore * will remove all tokens from the ignore list. - -For example: - - Header weeding @@ -2551,7 +2585,11 @@ unignore posted-to: - + + + +Ordering Displayed Headers + Usage: @@ -2593,6 +2631,7 @@ hdr_order From Date: From: To: Cc: Subject: + @@ -2761,7 +2800,14 @@ is *, all entries on alternates Mutt has a few nice features for handling mailing lists. In order to take advantage of them, you must specify which addresses belong to mailing lists, and which mailing -lists you are subscribed to. Once you have done this, the <list-reply> function will work for all known lists. +lists you are subscribed to. Mutt also has limited support for +auto-detecting mailing lists: it supports parsing +mailto: links in the common +List-Post: header which has the same effect as +specifying the list address via the lists command +(except the group feature). Once you have done this, the +<list-reply> +function will work for all known lists. Additionally, when you send a message to a subscribed list, mutt will add a Mail-Followup-To header to tell other users' mail user agents not to send copies of replies to your personal address. @@ -2774,7 +2820,8 @@ supported by all mail user agents. Adding it is not bullet-proof against receiving personal CCs of list messages. Also note that the generation of the Mail-Followup-To header is controlled by the $followup_to -configuration variable. +configuration variable since it's common practice on some mailing lists +to send Cc upons replies (which is more a group- than a list-reply). @@ -2786,24 +2833,29 @@ command. To mark it as subscribed, use subscribe. -You can use regular expressions with both commands. To mark all -messages sent to a specific bug report's address on mutt's bug +You can use regular expressions with both commands. To mark all +messages sent to a specific bug report's address on Debian's bug tracking system as list mail, for instance, you could say -subscribe [0-9]*@bugs.guug.de. Often, it's sufficient to just -give a portion of the list's e-mail address. + + + +subscribe [0-9]*.*@bugs.debian.org + + +as it's often, it's sufficient to just give a portion of the list's e-mail address. Specify as much of the address as you need to to remove ambiguity. For example, if you've subscribed to the Mutt mailing list, you will receive mail -addressed to mutt-users@mutt.org. So, to tell Mutt -that this is a mailing list, you could add lists mutt-users@ to your +addressed to mutt-users@mutt.org. So, to tell Mutt +that this is a mailing list, you could add lists mutt-users@ to your initialization file. To tell mutt that you are subscribed to it, -add subscribe mutt-users to your initialization file instead. +add subscribe mutt-users to your initialization file instead. If you also happen to get mail from someone whose address is -mutt-users@example.com, you could use -lists ^mutt-users@mutt\\.org$ -or subscribe ^mutt-users@mutt\\.org$ to +mutt-users@example.com, you could use +lists ^mutt-users@mutt\\.org$ +or subscribe ^mutt-users@mutt\\.org$ to match only mail from the actual list. @@ -2938,7 +2990,7 @@ In cases where new mail detection for Mbox or Mmdf folders appears to be unreliable, the $check_mbox_size option can be used to make Mutt track and consult file sizes for new -mail detection instead. +mail detection instead which won't work for size-neutral changes. @@ -2969,12 +3021,14 @@ mail detection instead. The my_hdr command allows you to create your own header -fields which will be added to every message you send. +fields which will be added to every message you send and appear in the +editor if $edit_headers is set. For example, if you would like to add an Organization: header field to -all of your outgoing messages, you can put the command +all of your outgoing messages, you can put the command something like +shown in in your .muttrc. @@ -2984,10 +3038,6 @@ my_hdr Organization: A Really Big Company, Anytown, USA - -in your .muttrc. - - Space characters are not allowed between the keyword and @@ -3044,10 +3094,6 @@ expandos of $index_format to mailbox after it was expanded. - -Examples: - - Using %-expandos in <literal>save-hook</literal> @@ -3101,12 +3147,10 @@ expandos of $index_format to See for information on the exact format of pattern. - -Example: fcc-hook [@.]aol\\.com$ +spammers - +fcc-hook [@.]aol\\.com$ +spammers -The above will save a copy of all messages going to the aol.com domain to +...will save a copy of all messages going to the aol.com domain to the `+spammers' mailbox by default. Also see the fcc-save-hook command. @@ -3190,7 +3234,7 @@ and replies. -reply-hooks are matched before the send-hook, regardless +reply-hooks are matched before the send-hook, regardless of the order specified in the user's configuration file. @@ -3222,12 +3266,12 @@ signatures based upon the recipients. -send-hook's are only executed once after getting the initial +send-hook's are only executed once after getting the initial list of recipients. Adding a recipient after replying or editing the message will not cause any send-hook to be executed. Also note that -my_hdr commands which modify recipient headers, or the message's +my_hdr commands which modify recipient headers, or the message's subject, don't have any effect on the current message when executed -from a send-hook. +from a send-hook. @@ -3322,8 +3366,8 @@ This command adds the named string to the keyboard buffer. The string may contain control characters, key names and function names like the sequence string in the macro command. You may use it to automatically run a sequence of commands at startup, or when entering -certain folders. For example, the following command will automatically -collapse all threads when entering a folder: +certain folders. For example, +shows how to automatically collapse all threads when entering a folder. @@ -3353,7 +3397,8 @@ folder-hook . 'push <collapse-all>' This command can be used to execute any function. Functions are listed in the function reference. -exec function is equivalent to push <function>. +exec function is equivalent to +push <function>. @@ -3397,7 +3442,7 @@ a match. Negative final scores are rounded up to 0. -The unscore command removes score entries from the list. You must +The unscore command removes score entries from the list. You must specify the same pattern specified in the score command for it to be removed. The pattern * is a special token which means to clear the list of all score entries. @@ -3460,15 +3505,15 @@ the first back-reference in the regex, %2 with the sec If you're using multiple spam filters, a message can have more than one spam-related header. You can define spam patterns for each filter you use. If a message matches two or more of these patterns, and -the $spam_separator variable is set to a string, then the +the $spam_separator variable is set to a string, then the message's spam tag will consist of all the format strings joined -together, with the value of $spam_separator separating +together, with the value of $spam_separator separating them. -For example, suppose I use DCC, SpamAssassin, and PureMessage. I might -define these spam settings: +For example, suppose one uses DCC, SpamAssassin, and PureMessage, then +the configuration might look like in . @@ -3482,7 +3527,7 @@ set spam_separator=", " -If I then received a message that DCC registered with many hits +If then a message is received that DCC registered with many hits under the Fuz2 checksum, and that PureMessage registered with a 97% probability of being spam, that message's spam tag would read 90+/DCC-Fuz2, 97/PM. (The four characters before =many in a @@ -3490,14 +3535,14 @@ DCC report indicate the checksum used -- in this case, Fuz2.) -If the $spam_separator variable is unset, then each +If the $spam_separator variable is unset, then each spam pattern match supersedes the previous one. Instead of getting joined format strings, you'll get only the last one to match. The spam tag is what will be displayed in the index when you use -%H in the $index_format variable. It's also the +%H in the $index_format variable. It's also the string that the ˜H pattern-matching expression matches against for <search> and <limit> functions. And it's what sorting by spam attribute will use as a sort key. @@ -3847,9 +3892,9 @@ macro pager ,x '\ Since mutt expands such values already when parsing the configuration file(s), the value of $my_delete in the -last example would be the value of $delete exactly +last example would be the value of $delete exactly as it was at that point during parsing the configuration file. If -another statement would change the value for $delete +another statement would change the value for $delete later in the same or another file, it would have no effect on $my_delete. However, the expansion can be deferred to runtime, as shown in the next example, when escaping the @@ -3950,7 +3995,7 @@ through the mutt configuration, especially in the $index_format, $pager_format, $status_format, -and other *_format variables. These can be very straightforward, +and other related variables. These can be very straightforward, and it's quite possible you already know how to use them. @@ -3967,7 +4012,7 @@ too. Those are our concern here. Some of the modifiers are borrowed right out of C (though you might know them from Perl, Python, shell, or another language). These are -the [-]m.n modifiers, as in %-12.12s. As with +the [-]m.n modifiers, as in %-12.12s. As with such programming languages, these modifiers allow you to specify the minimum and maximum size of the resulting string, as well as its justification. If the - sign follows the percent, the string will @@ -3978,11 +4023,8 @@ will be padded out with spaces. If a decimal point and another number follow, that's the maximum space allowable -- the string will not be permitted to exceed that width, no matter its natural size. Each of these three elements is optional, so that all these are legal format -strings: -%-12s -%4c -%.15F -%-12.15L +strings: %-12s, %4c, +%.15F and %-12.15L. @@ -3991,10 +4033,10 @@ symbol (=) as a numeric prefix (like the minus above), it will force the string to be centered within its minimum space range. For example, %=14y will reserve 14 characters for the %y expansion -- that's the X-Label: header, in -$index_format. If the expansion +$index_format. If the expansion results in a string less than 14 characters, it will be centered in a 14-character space. If the X-Label for a message were "test", that -expansion would look like test . +expansion would look like      test     . @@ -4122,7 +4164,7 @@ case letter, and case insensitive otherwise. -Note that \ +\ must be quoted if used for a regular expression in an initialization command: \\. @@ -4136,7 +4178,7 @@ expressions, by using various operators to combine smaller expressions. -Note that the regular expression can be enclosed/delimited by either " +The regular expression can be enclosed/delimited by either " or ' which is useful if the regular expression includes a white-space character. See for more information on " and ' delimiter processing. To match a @@ -4160,8 +4202,8 @@ the empty string at the beginning and end of a line. A list of characters enclosed by [ and ] matches any single character in that list; if the first character of the list -is a caret ˆ then it matches any character not in the -list. For example, the regular expression [0123456789] +is a caret ˆ then it matches any character not in the +list. For example, the regular expression [0123456789] matches any single digit. A range of ASCII characters may be specified by giving the first and last characters, separated by a hyphen -. Most metacharacters lose their special meaning inside @@ -4210,8 +4252,8 @@ brackets of a character list. Note that the brackets in these class names are part of the symbolic names, and must be included in addition to the brackets delimiting the bracket list. For -example, [[:digit:]] is equivalent to -[0-9]. +example, [[:digit:]] is equivalent to +[0-9]. @@ -4231,8 +4273,8 @@ sorting purposes: A collating symbol is a multi-character collating element enclosed in [. and .]. For example, if ch is a collating -element, then [[.ch.]] is a regexp that matches -this collating element, while [ch] is a regexp that +element, then [[.ch.]] is a regexp that matches +this collating element, while [ch] is a regexp that matches either c or h. @@ -4245,7 +4287,7 @@ An equivalence class is a locale-specific name for a list of characters that are equivalent. The name is enclosed in [= and =]. For example, the name e might be used to represent all of è é and e. In this case, -[[=e=]] is a regexp that matches any of +[[=e=]] is a regexp that matches any of è, é and e. @@ -4418,7 +4460,7 @@ are allowed, too. Special attention has to be -made when using regular expressions inside of patterns. Specifically, +payed when using regular expressions inside of patterns. Specifically, Mutt's parser for these patterns will strip one level of backslash (\), which is normally used for quoting. If it is your intention to use a backslash in the regular expression, you will need to use two backslashes @@ -4458,7 +4500,7 @@ This example matches all mails which only has recipients from Germany. Mutt supports two versions of so called simple searches. These are issued if the query entered for searching, limiting and similar -operations does not seem contain a valid pattern modifier (i.e. it does not contain +operations does not seem to contain a valid pattern modifier (i.e. it does not contain one of these characters: ˜, = or %). If the query is supposed to contain one of these special characters, they must be escaped by prepending a backslash (\). @@ -4521,7 +4563,7 @@ example: would select messages which contain the word mutt in the list of -recipients and that have the word elkins in the From header +recipients and that have the word elkins in the From header field. @@ -4579,17 +4621,14 @@ or Ed +SomeoneElse: If a regular expression contains parenthesis, or a vertical bar -("|"), you must enclose the expression in double or single quotes since +("|"), you must enclose the expression in double or single quotes since those characters are also used to separate different parts of Mutt's pattern language. For example: ~f "me@(mutt\.org|cs\.hmc\.edu)" - - - - Without the quotes, the parenthesis wouldn't end. This would be separated to two OR'd patterns: ˜f me@(mutt\.org and cs\.hmc\.edu). They are never what you want. + @@ -4600,8 +4639,11 @@ and cs\.hmc\.edu). They are never what you want. Mutt supports two types of dates, absolute and relative. + +Absolute Dates + -Absolute. Dates must be in DD/MM/YY format (month and year are +Dates must be in DD/MM/YY format (month and year are optional, defaulting to the current month and year). An example of a valid range of dates is: @@ -4619,7 +4661,7 @@ only messages sent on the given date will be selected. -Error Margins. You can add error margins to absolute dates. +You can add error margins to absolute dates. An error margin is a sign (+ or -), followed by a digit, followed by one of the units in . As a special case, you can replace the sign by a * character, which is equivalent to giving identical plus and minus error margins. @@ -4649,8 +4691,13 @@ you'd use the following pattern: Limit to messages matching: ~d 15/1/2001*2w + + + +Relative Dates + -Relative. This type of date is relative to the current date, and may +This type of date is relative to the current date, and may be specified as: @@ -4658,19 +4705,19 @@ be specified as: ->offset (messages older than offset units) +>offset for messages older than offset units -<offset (messages newer than offset units) +<offset for messages newer than offset units -=offset (messages exactly offset units old) +=offset for messages exactly offset units old @@ -4691,12 +4738,14 @@ Limit to messages matching: ~d <1m All dates used when searching are relative to the -local time zone, so unless you change the setting of your $index_format to include a -%[...] format, these are not the dates shown +local time zone, so unless you change the setting of your $index_format to include a +%[...] format, these are not the dates shown in the main index. + + @@ -4719,7 +4768,7 @@ matching syntax. Once you have tagged the desired messages, you can use the tag-prefix operator, which is the ; (semicolon) key by default. -When the tag-prefix operator is used, the next operation will +When the tag-prefix operator is used, the next operation will be applied to all tagged messages if that operation can be used in that manner. If the $auto_tag variable is set, the next operation applies to the tagged messages @@ -4728,10 +4777,10 @@ automatically, without requiring the tag-prefix. In macros or push commands, -you can use the tag-prefix-cond operator. If there are no tagged -messages, mutt will "eat" the rest of the macro to abort it's execution. -Mutt will stop "eating" the macro when it encounters the end-cond -operator; after this operator the rest of the macro will be executed as +you can use the <tag-prefix-cond> operator. If there are no tagged +messages, mutt will eat the rest of the macro to abort it's execution. +Mutt will stop eating the macro when it encounters the <end-cond> +operator; after this operator the rest of the macro will be executed as normal. @@ -4747,7 +4796,7 @@ you may wish to tailor your configuration based upon which mailbox you are reading, or to whom you are sending mail. In the Mutt world, a hook consists of a regular expression or pattern along with a -configuration option/command. See +configuration option/command. See: @@ -4838,20 +4887,28 @@ for specific details on each type of hook available. If a hook changes configuration settings, these changes remain effective until the end of the current mutt session. As this is generally -not desired, a default hook needs to be added before all other hooks to -restore configuration defaults. Here is an example with send-hook and the -my_hdr directive: +not desired, a default hook needs to be added before all +other hooks of that type to restore configuration defaults. - -Combining <literal>send-hook</literal> and <literal>my_hdr</literal> + +Specifying a <quote>default</quote> hook send-hook . 'unmy_hdr From:' send-hook ~C'^b@b\.b$' my_hdr from: c@c.c + +In , by default the value of +$from +and $realname +is not overridden. When sending messages either To: or Cc: +to <b@b.b>, the From: header is changed to +<c@c.c>. + + Message Matching in Hooks @@ -5037,7 +5094,8 @@ using file-level synchronization tools. There are a number of built in shortcuts which refer to specific mailboxes. These shortcuts can be used anywhere you are prompted for a file or mailbox -path. +path or in path-related configuration variables. Note that these only +work at the beginning of a string. @@ -5092,6 +5150,16 @@ path. + +For example, to store a copy of outgoing messages in the folder they +were composed in, +a folder-hook can +be used to set $record: + + + +folder-hook . 'set record=ˆ' + @@ -5111,10 +5179,10 @@ Now that Mutt knows what your mailing lists are, it can do several things, the first of which is the ability to show the name of a list through which you received a message (i.e., of a subscribed list) in the index menu display. This is useful to distinguish between -personal and list mail in the same mailbox. In the $index_format variable, the escape %L -will return the string To <list> when list appears in the +personal and list mail in the same mailbox. In the $index_format variable, the expando %L +will print the string To <list> when list appears in the To field, and Cc <list> when it appears in the Cc -field (otherwise it returns the name of the author). +field (otherwise it prints the name of the author). @@ -5144,7 +5212,7 @@ one of the mailing lists you are subscribed to. Conversely, when group-replying or list-replying to a message which has a Mail-Followup-To header, mutt will respect this header if the $honor_followup_to configuration -variable is set. Using list-reply will in this case also make sure +variable is set. Using list-reply will in this case also make sure that the reply goes to the mailing list, even if it's not specified in the list of recipients in the Mail-Followup-To. @@ -5176,7 +5244,7 @@ present. The X-Label: header field can be used to further identify mailing lists or list subject matter (or just to annotate messages individually). The $index_format variable's %y and -%Y escapes can be used to expand X-Label: fields in the +%Y expandos can be used to expand X-Label: fields in the index, and Mutt's pattern-matcher can match regular expressions to X-Label: fields with the ˜y selector. X-Label: is not a standard message header field, but it can easily be inserted by procmail @@ -5233,7 +5301,7 @@ the bottom of the screen. For the index, by default Mutt displays the number of mailboxes with new mail in the status bar, please refer to the -$index_format +$status_format variable for details. @@ -5251,7 +5319,7 @@ the mailboxes list containing new mail (if any), pressing Mutt has the ability to dynamically restructure threads that are broken either by misconfigured software or bad behavior from some -correspondents. This allows to clean your mailboxes formats) from these +correspondents. This allows to clean your mailboxes from these annoyances which make it hard to follow a discussion. @@ -5259,18 +5327,18 @@ annoyances which make it hard to follow a discussion. Linking threads -Some mailers tend to "forget" to correctly set the "In-Reply-To:" and -"References:" headers when replying to a message. This results in broken +Some mailers tend to forget to correctly set the In-Reply-To: and +References: headers when replying to a message. This results in broken discussions because Mutt has not enough information to guess the correct threading. You can fix this by tagging the reply, then moving to the parent message and using the <link-threads> function (bound to & by default). The -reply will then be connected to this "parent" message. +reply will then be connected to this parent message. You can also connect multiple children at once, tagging them and using the -tag-prefix command (';') or the auto_tag option. +<tag-prefix> command (';') or the $auto_tag option. @@ -5280,7 +5348,7 @@ tag-prefix command (';') or the auto_tag option. On mailing lists, some people are in the bad habit of starting a new -discussion by hitting "reply" to any message from the list and changing +discussion by hitting reply to any message from the list and changing the subject to a totally unrelated one. You can fix such threads by using the <break-thread> function (bound by default to #), which will turn the subthread starting from the @@ -5459,12 +5527,12 @@ If Mutt cannot deal with a MIME type, it will display a message like: The Attachment Menu -The default binding for view-attachments is `v', which displays the +The default binding for <view-attachments> is v, which displays the attachment menu for a message. The attachment menu displays a list of the attachments in a message. From the attachment menu, you can save, print, pipe, delete, and view attachments. You can apply these operations to a group of attachments at once, by tagging the attachments -and by using the tag-prefix operator. You can also reply to the +and by using the <tag-prefix> operator. You can also reply to the current message from this menu, and only the current attachment (or the attachments tagged) will be quoted in your reply. You can view attachments as text, or view them using the mailcap viewer definition. @@ -5508,16 +5576,16 @@ Attachments appear as follows: The '-' denotes that Mutt will delete the file after sending (or postponing, or canceling) the message. It can be toggled with the -toggle-unlink command (default: u). The next field is the MIME -content-type, and can be changed with the edit-type command +<toggle-unlink> command (default: u). The next field is the MIME +content-type, and can be changed with the <edit-type> command (default: ˆT). The next field is the encoding for the attachment, which allows a binary message to be encoded for transmission on 7bit -links. It can be changed with the edit-encoding command +links. It can be changed with the <edit-encoding> command (default: ˆE). The next field is the size of the attachment, rounded to kilobytes or megabytes. The next field is the filename, -which can be changed with the rename-file command (default: R). +which can be changed with the <rename-file> command (default: R). The final field is the description of the attachment, and can be -changed with the edit-description command (default: d). +changed with the <edit-description> command (default: d). @@ -5529,13 +5597,13 @@ changed with the edit-description command (default: d). When you add an attachment to your mail message, Mutt searches your -personal mime.types file at ${HOME}/.mime.types, and then -the system mime.types file at /usr/local/share/mutt/mime.types or +personal mime.types file at ${HOME}/.mime.types, and then +the system mime.types file at /usr/local/share/mutt/mime.types or /etc/mime.types -The mime.types file consist of lines containing a MIME type and a space +The mime.types file consist of lines containing a MIME type and a space separated list of extensions. For example: @@ -5556,12 +5624,12 @@ attach, it will look at the file. If the file is free of binary information, Mutt will assume that the file is plain text, and mark it as text/plain. If the file contains binary information, then Mutt will mark it as application/octet-stream. You can change the MIME -type that Mutt assigns to an attachment by using the edit-type +type that Mutt assigns to an attachment by using the <edit-type> command from the compose menu (default: ˆT). The MIME type is actually a major mime type followed by the sub-type, separated by a '/'. 6 major types: application, text, image, video, audio, and model have been approved after various internet discussions. Mutt recognizes all of these if the -appropriate entry is found in the mime.types file. It also recognizes other +appropriate entry is found in the mime.types file. It also recognizes other major mime types, such as the chemical type that is widely used in the molecular modeling community to pass molecular data in various forms to various molecular viewers. Non-recognized mime types should only be used @@ -5571,7 +5639,7 @@ if the recipient of the message is likely to be expecting such attachments. -MIME Viewer configuration with <literal>mailcap</literal> +MIME Viewer configuration with mailcap Mutt supports RFC 1524 MIME Configuration, in particular the Unix @@ -5905,8 +5973,8 @@ text/html; lynx %s In this example, Mutt will run the program RunningX which will return 0 if the X Window manager is running, and non-zero if it isn't. If RunningX returns 0, then Mutt will call netscape to display the -text/html object. If RunningX doesn't return 0, then Mutt will go on -to the next entry and use lynx to display the text/html object. +text/html object. If RunningX doesn't return 0, then Mutt will go on +to the next entry and use lynx to display the text/html object. @@ -5965,7 +6033,7 @@ for interactive viewing. The various commands defined in the mailcap files are passed to the -/bin/sh shell using the system() function. Before the +/bin/sh shell using the system(3) function. Before the command is passed to /bin/sh -c, it is parsed to expand various special parameters with information from Mutt. The keywords Mutt expands are: @@ -6116,12 +6184,9 @@ representation which you can view in the pager. -You then use the auto_view muttrc command to list the -content-types that you wish to view automatically. - - - -For instance, if you set auto_view to: +You then use the auto_view muttrc command to list the +content-types that you wish to view automatically. For instance, if you +set it to: @@ -6144,8 +6209,8 @@ application/postscript; ps2ascii %s; copiousoutput -unauto_view can be used to remove previous entries from the autoview list. -This can be used with message-hook to autoview messages based on size, etc. +unauto_view can be used to remove previous entries from the autoview list. +This can be used with message-hook to autoview messages based on size, etc. unauto_view * will remove all previous entries. @@ -6156,11 +6221,11 @@ This can be used with message-hook to autoview messages based on size, etc. Mutt has some heuristics for determining which attachment of a -multipart/alternative type to display. First, mutt will check the -alternative_order list to determine if one of the available types -is preferred. The alternative_order list consists of a number of -mimetypes in order, including support for implicit and explicit -wildcards, for example: +multipart/alternative type to display. First, mutt will check the +alternative_order list +to determine if one of the available types is preferred. It consists of +a number of mimetypes in order, including support for implicit and +explicit wildcards, for example: @@ -6175,8 +6240,8 @@ look for any type it knows how to handle. -To remove a MIME type from the alternative_order list, use the -unalternative_order command. +To remove a MIME type from the alternative_order list, use the +unalternative_order command. @@ -6190,7 +6255,7 @@ attachment-counting and -searching support might be for you. You can make your message index display the number of qualifying attachments in each message, or search for messages by attachment count. You also can configure what kinds of attachments qualify for this feature with the -attachments and unattachments commands. +attachments and unattachments commands. @@ -6205,14 +6270,35 @@ or not. The syntax is: - -attachments {+|-}disposition mime-type -unattachments {+|-}disposition mime-type -attachments ? - + +attachments + +{ + | - }disposition + + +mime-type + + + + +unattachments + +{ + | - }disposition + + +mime-type + + + + +attachments + +? + + -Disposition is the attachment's Content-disposition type -- either +disposition is the attachment's Content-Disposition type -- either inline or attachment. You can abbreviate this to I or A. @@ -6226,7 +6312,7 @@ below of how this is useful. -Mime-type is, unsurprisingly, the MIME type of the attachment you want +mime-type is, unsurprisingly, the MIME type of the attachment you want to affect. A MIME type is always of the format major/minor, where major describes the broad category of document you're looking at, and minor describes the specific type within that category. The major @@ -6315,9 +6401,9 @@ it can be pasted elsewhere. Mutt's mime_lookup list specifies a list of mime-types that should not be treated according to their mailcap entry. This option is designed to -deal with binary types such as application/octet-stream. When an attachment's +deal with binary types such as application/octet-stream. When an attachment's mime-type is listed in mime_lookup, then the extension of the filename will -be compared to the list of extensions in the mime.types file. The mime-type +be compared to the list of extensions in the mime.types file. The mime-type associated with this extension will then be used to process the attachment according to the rules in the mailcap file and according to any other configuration options (such as auto_view) specified. Common usage would be: @@ -6328,9 +6414,9 @@ mime_lookup application/octet-stream application/X-Lotus-Manuscript -In addition, the unmime_lookup command may be used to disable this feature -for any particular mime-type if it had been set, for example, in a global -muttrc. +In addition, the unmime_lookup command may be +used to disable this feature for any particular mime-type if it had been +set, for example, in a global muttrc. @@ -6390,7 +6476,7 @@ system's default for the given protocol. -Since all protocols by mutt support authentication, the username may be +Since all protocols supported by mutt support, the username may be given directly in the URL instead of using the pop_user or imap_user variables. It may contain the @ symbol being used by many mail systems as part of the login name. A password can be @@ -6403,13 +6489,9 @@ The optional path is only relevant for IMAP. -For IMAP for example, you can select an alternative port by specifying it with the -server: imap://imapserver:port/INBOX. You can also specify different -username for each folder: imap://username@imapserver[:port]/INBOX +For IMAP for example, you can also specify different +usernames for each folder: imap://username@imapserver[:port]/INBOX or imap://username2@imapserver[:port]/path/to/folder. -Replacing imap:// by imaps:// -would make mutt attempt to connect using SSL or TLS on a different port -to encrypt the communication. @@ -6435,7 +6517,7 @@ are suffixed with s for secure communication. POP3 Support -If Mutt was compiled with POP3 support (by running the configure +If Mutt is compiled with POP3 support (by running the configure script with the --enable-pop flag), it has the ability to work with mailboxes located on a remote POP3 server and fetch mail for local browsing. @@ -6467,7 +6549,7 @@ point, Mutt runs exactly as if the mail had always been local. If you only need to fetch all messages to a local mailbox you should consider using a specialized program, such as -fetchmail, getmail or similar. +fetchmail(1), getmail(1) or similar. @@ -6509,7 +6591,7 @@ want to carefully tune the $mail_check and $timeout -variables. Personally I use +variables. Reasonable values are: @@ -6518,7 +6600,7 @@ set timeout=15 -with relatively good results over my slow modem line. +with relatively good results even over slow modem lines. @@ -6563,10 +6645,10 @@ the messages in that folder, you must use view-file instead You can create, delete and rename mailboxes with the -create-mailbox, delete-mailbox, and -rename-mailbox commands (default bindings: C, +<create-mailbox>, <delete-mailbox>, and +<rename-mailbox> commands (default bindings: C, d and r, respectively). You may also -subscribe and unsubscribe to mailboxes (normally +<subscribe> and <unsubscribe> to mailboxes (normally these are bound to s and u, respectively). @@ -6585,7 +6667,7 @@ NTLM authentication for you poor exchange users out there, but it has yet to be integrated into the main tree). There is also support for the pseudo-protocol ANONYMOUS, which allows you to log in to a public IMAP server without having an account. To use ANONYMOUS, simply make -your username blank or "anonymous". +your username blank or anonymous. @@ -6678,15 +6760,15 @@ from most-secure to least-secure. If you happen to have accounts on multiple IMAP, POP and/or SMTP servers, you may find managing all the authentication settings inconvenient and -error-prone. The account-hook command may help. This hook works like -folder-hook but is invoked whenever you access a remote mailbox +error-prone. The account-hook command may help. This hook works like +folder-hook but is invoked whenever you access a remote mailbox (including inside the folder browser), not just when you open the -mailbox which includes (for example) polling for new mail, storing Fcc +mailbox. This includes (for example) polling for new mail, storing Fcc messages and saving messages to a folder. As a consequence, -account-hook should only be used to set connection-related settings such +account-hook should only be used to set connection-related settings such as passwords or tunnel commands but not settings such as sender address or name (because in general it should be considered unpredictable -which account-hook was last used). +which account-hook was last used). @@ -6745,24 +6827,6 @@ result in lower performance), but one file per folder if it points to a directory. - -For the one-file-per-folder case, database files for remote folders -will be named according to their URL while database files for local -folders will be named by the MD5 checksums of their path. These database -files may be safely removed if a system is short on space. You -can compute the name of the header cache file for a particular local folder -through a command like the following: - - - -$ printf '%s' '/path/to/folder' | md5sum - - - -The md5sum command may also be -named md5, depending on your operating system. - - @@ -6788,12 +6852,7 @@ For configuration, the variable proto:user@hostname where proto is either pop or imap. Within -there for each folder, mutt stores messages in single files (just -like Maildir) so that with manual symlink creation these cache -directories can be examined with mutt as read-only Maildir folders. - - - +there for each folder, mutt stores messages in single files. All files can be removed as needed if the consumed disk space becomes an issue as mutt will silently fetch missing items again. @@ -6860,8 +6919,7 @@ For remote folders (IMAP and POP) as well as folders using one-file-per message storage (Maildir and MH), mutt's performance can be greatly improved using header caching. -Using a single database per folder may further increase -performance. +using a single database per folder. @@ -6997,7 +7055,7 @@ to send messages from the command line as well. -xsimulate the mailx(1) compose mode -yshow a menu containing the files specified by the mailboxes command -zexit immediately if there are no messages in the mailbox --Zopen the first folder with new message,exit immediately if none +-Zopen the first folder with new message, exit immediately if none @@ -7030,9 +7088,6 @@ To compose a new message muttrc - -file - address @@ -7042,12 +7097,11 @@ To compose a new message subject - + file --- - +-- address @@ -7061,23 +7115,30 @@ Mutt also supports a batch mode to send prepared messages. Simpl input from the file you wish to send. For example, - -mutt -s "data set for run #2" professor@bigschool.edu -< ˜/run2.dat - + +mutt -s "data set for run #2" professor@bigschool.edu < ˜/run2.dat -This command will send a message to professor@bigschool.edu with a subject +will send a message to <professor@bigschool.edu> with a subject of data set for run #2. In the body of the message will be the contents of the file ˜/run2.dat. -All files passed with -a file will be attached as a MIME +All files passed with -a file will be attached as a MIME part to the message. To attach several files, use -- to separate files and -recipient addresses: mutt -a *.png -- some@one.org +recipient addresses: + +mutt -a *.png -- some@one.org + + + +The -a option must be last in the option list. + + + @@ -7116,9 +7177,7 @@ The following are the commands understood by mutt. address - - unalias @@ -7150,9 +7209,7 @@ The following are the commands understood by mutt. regexp - - unalternates @@ -7180,9 +7237,7 @@ The following are the commands understood by mutt. mimetype - - unalternative-order @@ -7196,6 +7251,28 @@ The following are the commands understood by mutt. + + +attachments + +{ + | - }disposition + + +mime-type + + + + +unattachments + +{ + | - }disposition + + +mime-type + + + + auto-view @@ -7206,8 +7283,6 @@ The following are the commands understood by mutt. mimetype - - unauto-view @@ -7309,9 +7384,7 @@ The following are the commands understood by mutt. pattern - - uncolor @@ -7323,6 +7396,18 @@ The following are the commands understood by mutt. + + +crypt-hook + +pattern + + +keyid + + + + exec @@ -7389,9 +7474,7 @@ The following are the commands understood by mutt. - - ungroup @@ -7424,9 +7507,7 @@ The following are the commands understood by mutt. header - - unhdr_order @@ -7450,9 +7531,7 @@ The following are the commands understood by mutt. pattern - - unignore @@ -7480,9 +7559,7 @@ The following are the commands understood by mutt. regexp - - unlists @@ -7528,9 +7605,7 @@ The following are the commands understood by mutt. mailbox - - unmailboxes @@ -7578,9 +7653,7 @@ The following are the commands understood by mutt. mimetype - - unmime-lookup @@ -7633,9 +7706,7 @@ The following are the commands understood by mutt. pattern - - unmono @@ -7659,9 +7730,7 @@ The following are the commands understood by mutt. string - - unmy_hdr @@ -7675,18 +7744,6 @@ The following are the commands understood by mutt. - - -crypt-hook - -pattern - - -keyid - - - - push @@ -7696,18 +7753,6 @@ The following are the commands understood by mutt. - - -reset - -variable - - -variable - - - - save-hook @@ -7730,9 +7775,7 @@ The following are the commands understood by mutt. value - - unscore @@ -7799,9 +7842,17 @@ The following are the commands understood by mutt. - - + +toggle + +variable + + +variable + + + unset @@ -7811,6 +7862,16 @@ The following are the commands understood by mutt. variable + + +reset + +variable + + +variable + + @@ -7832,9 +7893,7 @@ The following are the commands understood by mutt. format - - nospam @@ -7862,9 +7921,7 @@ The following are the commands understood by mutt. regexp - - unsubscribe @@ -7882,18 +7939,6 @@ The following are the commands understood by mutt. - - -toggle - -variable - - -variable - - - - unhook -- 2.40.0