X-Git-Url: https://git.llucax.com/software/mutt-debian.git/blobdiff_plain/647ac5444d022537a1f0854dd309494c511dfe07..ee66c1452ad6f627879c9ec8156342f5e90c2253:/doc/manual.txt diff --git a/doc/manual.txt b/doc/manual.txt index 668b97c..659b0ac 100644 --- a/doc/manual.txt +++ b/doc/manual.txt @@ -4,7 +4,7 @@ Michael Elkins -version 1.5.20 (2009-06-14) +version 1.5.21 (2010-09-15) Abstract @@ -21,7 +21,7 @@ Table of Contents 3. Getting Mutt 4. Mutt Online Resources 5. Contributing to Mutt - 6. Typograhical Conventions + 6. Typographical Conventions 7. Copyright 2. Getting Started @@ -73,8 +73,9 @@ Table of Contents 9. Using Color and Mono Video Attributes 10. Message Header Display - 10.1. Selecting Headers - 10.2. Ordering Displayed Headers + 10.1. Header Display + 10.2. Selecting Headers + 10.3. Ordering Displayed Headers 11. Alternative Addresses 12. Mailing Lists @@ -96,6 +97,7 @@ Table of Contents 26.1. Variable Types 26.2. Commands 26.3. User-Defined Variables + 26.4. Type Conversions 27. Reading Initialization Commands From Another File 28. Removing Hooks @@ -108,40 +110,46 @@ Table of Contents 4. Advanced Usage - 1. Regular Expressions - 2. Patterns: Searching, Limiting and Tagging + 1. Character Set Handling + 2. Regular Expressions + 3. Patterns: Searching, Limiting and Tagging - 2.1. Pattern Modifier - 2.2. Simple Searches - 2.3. Nesting and Boolean Operators - 2.4. Searching by Date + 3.1. Pattern Modifier + 3.2. Simple Searches + 3.3. Nesting and Boolean Operators + 3.4. Searching by Date - 3. Using Tags - 4. Using Hooks + 4. Using Tags + 5. Using Hooks - 4.1. Message Matching in Hooks + 5.1. Message Matching in Hooks - 5. External Address Queries - 6. Mailbox Formats - 7. Mailbox Shortcuts - 8. Handling Mailing Lists - 9. Handling multiple folders - 10. Editing Threads + 6. External Address Queries + 7. Mailbox Formats + 8. Mailbox Shortcuts + 9. Handling Mailing Lists + 10. New Mail Detection - 10.1. Linking Threads - 10.2. Breaking Threads + 10.1. How New Mail Detection Works + 10.2. Polling For New Mail - 11. Delivery Status Notification (DSN) Support - 12. Start a WWW Browser on URLs - 13. Miscellany + 11. Editing Threads + + 11.1. Linking Threads + 11.2. Breaking Threads + + 12. Delivery Status Notification (DSN) Support + 13. Start a WWW Browser on URLs + 14. Miscellany 5. Mutt's MIME Support 1. Using MIME in Mutt - 1.1. Viewing MIME Messages in the Pager - 1.2. The Attachment Menu - 1.3. The Compose Menu + 1.1. MIME Overview + 1.2. Viewing MIME Messages in the Pager + 1.3. The Attachment Menu + 1.4. The Compose Menu 2. MIME Type Configuration with mime.types 3. MIME Viewer Configuration with Mailcap @@ -176,7 +184,8 @@ Table of Contents 7.1. Header Caching 7.2. Body Caching - 7.3. Maintenance + 7.3. Cache Directories + 7.4. Maintenance 8. Exact Address Generation 9. Sending Anonymous Messages via Mixmaster @@ -322,198 +331,200 @@ Table of Contents 3.116. keep_flagged 3.117. locale 3.118. mail_check - 3.119. mailcap_path - 3.120. mailcap_sanitize - 3.121. maildir_header_cache_verify - 3.122. maildir_trash - 3.123. mark_old - 3.124. markers - 3.125. mask - 3.126. mbox - 3.127. mbox_type - 3.128. menu_context - 3.129. menu_move_off - 3.130. menu_scroll - 3.131. message_cache_clean - 3.132. message_cachedir - 3.133. message_format - 3.134. meta_key - 3.135. metoo - 3.136. mh_purge - 3.137. mh_seq_flagged - 3.138. mh_seq_replied - 3.139. mh_seq_unseen - 3.140. mime_forward - 3.141. mime_forward_decode - 3.142. mime_forward_rest - 3.143. mix_entry_format - 3.144. mixmaster - 3.145. move - 3.146. narrow_tree - 3.147. net_inc - 3.148. pager - 3.149. pager_context - 3.150. pager_format - 3.151. pager_index_lines - 3.152. pager_stop - 3.153. pgp_auto_decode - 3.154. pgp_autoinline - 3.155. pgp_check_exit - 3.156. pgp_clearsign_command - 3.157. pgp_decode_command - 3.158. pgp_decrypt_command - 3.159. pgp_encrypt_only_command - 3.160. pgp_encrypt_sign_command - 3.161. pgp_entry_format - 3.162. pgp_export_command - 3.163. pgp_getkeys_command - 3.164. pgp_good_sign - 3.165. pgp_ignore_subkeys - 3.166. pgp_import_command - 3.167. pgp_list_pubring_command - 3.168. pgp_list_secring_command - 3.169. pgp_long_ids - 3.170. pgp_mime_auto - 3.171. pgp_replyinline - 3.172. pgp_retainable_sigs - 3.173. pgp_show_unusable - 3.174. pgp_sign_as - 3.175. pgp_sign_command - 3.176. pgp_sort_keys - 3.177. pgp_strict_enc - 3.178. pgp_timeout - 3.179. pgp_use_gpg_agent - 3.180. pgp_verify_command - 3.181. pgp_verify_key_command - 3.182. pipe_decode - 3.183. pipe_sep - 3.184. pipe_split - 3.185. pop_auth_try_all - 3.186. pop_authenticators - 3.187. pop_checkinterval - 3.188. pop_delete - 3.189. pop_host - 3.190. pop_last - 3.191. pop_pass - 3.192. pop_reconnect - 3.193. pop_user - 3.194. post_indent_string - 3.195. postpone - 3.196. postponed - 3.197. preconnect - 3.198. print - 3.199. print_command - 3.200. print_decode - 3.201. print_split - 3.202. prompt_after - 3.203. query_command - 3.204. query_format - 3.205. quit - 3.206. quote_regexp - 3.207. read_inc - 3.208. read_only - 3.209. realname - 3.210. recall - 3.211. record - 3.212. reply_regexp - 3.213. reply_self - 3.214. reply_to - 3.215. resolve - 3.216. reverse_alias - 3.217. reverse_name - 3.218. reverse_realname - 3.219. rfc2047_parameters - 3.220. save_address - 3.221. save_empty - 3.222. save_history - 3.223. save_name - 3.224. score - 3.225. score_threshold_delete - 3.226. score_threshold_flag - 3.227. score_threshold_read - 3.228. search_context - 3.229. send_charset - 3.230. sendmail - 3.231. sendmail_wait - 3.232. shell - 3.233. sig_dashes - 3.234. sig_on_top - 3.235. signature - 3.236. simple_search - 3.237. sleep_time - 3.238. smart_wrap - 3.239. smileys - 3.240. smime_ask_cert_label - 3.241. smime_ca_location - 3.242. smime_certificates - 3.243. smime_decrypt_command - 3.244. smime_decrypt_use_default_key - 3.245. smime_default_key - 3.246. smime_encrypt_command - 3.247. smime_encrypt_with - 3.248. smime_get_cert_command - 3.249. smime_get_cert_email_command - 3.250. smime_get_signer_cert_command - 3.251. smime_import_cert_command - 3.252. smime_is_default - 3.253. smime_keys - 3.254. smime_pk7out_command - 3.255. smime_sign_command - 3.256. smime_sign_opaque_command - 3.257. smime_timeout - 3.258. smime_verify_command - 3.259. smime_verify_opaque_command - 3.260. smtp_authenticators - 3.261. smtp_pass - 3.262. smtp_url - 3.263. sort - 3.264. sort_alias - 3.265. sort_aux - 3.266. sort_browser - 3.267. sort_re - 3.268. spam_separator - 3.269. spoolfile - 3.270. ssl_ca_certificates_file - 3.271. ssl_client_cert - 3.272. ssl_force_tls - 3.273. ssl_min_dh_prime_bits - 3.274. ssl_starttls - 3.275. ssl_use_sslv2 - 3.276. ssl_use_sslv3 - 3.277. ssl_use_tlsv1 - 3.278. ssl_usesystemcerts - 3.279. ssl_verify_dates - 3.280. ssl_verify_host - 3.281. status_chars - 3.282. status_format - 3.283. status_on_top - 3.284. strict_threads - 3.285. suspend - 3.286. text_flowed - 3.287. thorough_search - 3.288. thread_received - 3.289. tilde - 3.290. time_inc - 3.291. timeout - 3.292. tmpdir - 3.293. to_chars - 3.294. tunnel - 3.295. uncollapse_jump - 3.296. use_8bitmime - 3.297. use_domain - 3.298. use_envelope_from - 3.299. use_from - 3.300. use_idn - 3.301. use_ipv6 - 3.302. user_agent - 3.303. visual - 3.304. wait_key - 3.305. weed - 3.306. wrap - 3.307. wrap_search - 3.308. wrapmargin - 3.309. write_bcc - 3.310. write_inc + 3.119. mail_check_recent + 3.120. mailcap_path + 3.121. mailcap_sanitize + 3.122. maildir_header_cache_verify + 3.123. maildir_trash + 3.124. mark_old + 3.125. markers + 3.126. mask + 3.127. mbox + 3.128. mbox_type + 3.129. menu_context + 3.130. menu_move_off + 3.131. menu_scroll + 3.132. message_cache_clean + 3.133. message_cachedir + 3.134. message_format + 3.135. meta_key + 3.136. metoo + 3.137. mh_purge + 3.138. mh_seq_flagged + 3.139. mh_seq_replied + 3.140. mh_seq_unseen + 3.141. mime_forward + 3.142. mime_forward_decode + 3.143. mime_forward_rest + 3.144. mix_entry_format + 3.145. mixmaster + 3.146. move + 3.147. narrow_tree + 3.148. net_inc + 3.149. pager + 3.150. pager_context + 3.151. pager_format + 3.152. pager_index_lines + 3.153. pager_stop + 3.154. pgp_auto_decode + 3.155. pgp_autoinline + 3.156. pgp_check_exit + 3.157. pgp_clearsign_command + 3.158. pgp_decode_command + 3.159. pgp_decrypt_command + 3.160. pgp_encrypt_only_command + 3.161. pgp_encrypt_sign_command + 3.162. pgp_entry_format + 3.163. pgp_export_command + 3.164. pgp_getkeys_command + 3.165. pgp_good_sign + 3.166. pgp_ignore_subkeys + 3.167. pgp_import_command + 3.168. pgp_list_pubring_command + 3.169. pgp_list_secring_command + 3.170. pgp_long_ids + 3.171. pgp_mime_auto + 3.172. pgp_replyinline + 3.173. pgp_retainable_sigs + 3.174. pgp_show_unusable + 3.175. pgp_sign_as + 3.176. pgp_sign_command + 3.177. pgp_sort_keys + 3.178. pgp_strict_enc + 3.179. pgp_timeout + 3.180. pgp_use_gpg_agent + 3.181. pgp_verify_command + 3.182. pgp_verify_key_command + 3.183. pipe_decode + 3.184. pipe_sep + 3.185. pipe_split + 3.186. pop_auth_try_all + 3.187. pop_authenticators + 3.188. pop_checkinterval + 3.189. pop_delete + 3.190. pop_host + 3.191. pop_last + 3.192. pop_pass + 3.193. pop_reconnect + 3.194. pop_user + 3.195. post_indent_string + 3.196. postpone + 3.197. postponed + 3.198. preconnect + 3.199. print + 3.200. print_command + 3.201. print_decode + 3.202. print_split + 3.203. prompt_after + 3.204. query_command + 3.205. query_format + 3.206. quit + 3.207. quote_regexp + 3.208. read_inc + 3.209. read_only + 3.210. realname + 3.211. recall + 3.212. record + 3.213. reply_regexp + 3.214. reply_self + 3.215. reply_to + 3.216. resolve + 3.217. reverse_alias + 3.218. reverse_name + 3.219. reverse_realname + 3.220. rfc2047_parameters + 3.221. save_address + 3.222. save_empty + 3.223. save_history + 3.224. save_name + 3.225. score + 3.226. score_threshold_delete + 3.227. score_threshold_flag + 3.228. score_threshold_read + 3.229. search_context + 3.230. send_charset + 3.231. sendmail + 3.232. sendmail_wait + 3.233. shell + 3.234. sig_dashes + 3.235. sig_on_top + 3.236. signature + 3.237. simple_search + 3.238. sleep_time + 3.239. smart_wrap + 3.240. smileys + 3.241. smime_ask_cert_label + 3.242. smime_ca_location + 3.243. smime_certificates + 3.244. smime_decrypt_command + 3.245. smime_decrypt_use_default_key + 3.246. smime_default_key + 3.247. smime_encrypt_command + 3.248. smime_encrypt_with + 3.249. smime_get_cert_command + 3.250. smime_get_cert_email_command + 3.251. smime_get_signer_cert_command + 3.252. smime_import_cert_command + 3.253. smime_is_default + 3.254. smime_keys + 3.255. smime_pk7out_command + 3.256. smime_sign_command + 3.257. smime_sign_opaque_command + 3.258. smime_timeout + 3.259. smime_verify_command + 3.260. smime_verify_opaque_command + 3.261. smtp_authenticators + 3.262. smtp_pass + 3.263. smtp_url + 3.264. sort + 3.265. sort_alias + 3.266. sort_aux + 3.267. sort_browser + 3.268. sort_re + 3.269. spam_separator + 3.270. spoolfile + 3.271. ssl_ca_certificates_file + 3.272. ssl_client_cert + 3.273. ssl_force_tls + 3.274. ssl_min_dh_prime_bits + 3.275. ssl_starttls + 3.276. ssl_use_sslv2 + 3.277. ssl_use_sslv3 + 3.278. ssl_use_tlsv1 + 3.279. ssl_usesystemcerts + 3.280. ssl_verify_dates + 3.281. ssl_verify_host + 3.282. status_chars + 3.283. status_format + 3.284. status_on_top + 3.285. strict_threads + 3.286. suspend + 3.287. text_flowed + 3.288. thorough_search + 3.289. thread_received + 3.290. tilde + 3.291. time_inc + 3.292. timeout + 3.293. tmpdir + 3.294. to_chars + 3.295. tunnel + 3.296. uncollapse_jump + 3.297. use_8bitmime + 3.298. use_domain + 3.299. use_envelope_from + 3.300. use_from + 3.301. use_idn + 3.302. use_ipv6 + 3.303. user_agent + 3.304. visual + 3.305. wait_key + 3.306. weed + 3.307. wrap + 3.308. wrap_headers + 3.309. wrap_search + 3.310. wrapmargin + 3.311. write_bcc + 3.312. write_inc 4. Functions @@ -522,13 +533,13 @@ Table of Contents 4.3. Pager Menu 4.4. Alias Menu 4.5. Query Menu - 4.6. Attach Menu + 4.6. Attachment Menu 4.7. Compose Menu 4.8. Postpone Menu 4.9. Browser Menu 4.10. Pgp Menu 4.11. Smime Menu - 4.12. Mix Menu + 4.12. Mixmaster Menu 4.13. Editor Menu 10. Miscellany @@ -559,26 +570,28 @@ List of Tables 4.4. Pattern modifiers 4.5. Simple search keywords 4.6. Date units +4.7. Mailbox shortcuts +5.1. Supported MIME types 9.1. Command line options -9.2. Default generic Function Bindings -9.3. Default index Function Bindings -9.4. Default pager Function Bindings -9.5. Default alias Function Bindings -9.6. Default query Function Bindings -9.7. Default attach Function Bindings -9.8. Default compose Function Bindings -9.9. Default postpone Function Bindings -9.10. Default browser Function Bindings -9.11. Default pgp Function Bindings -9.12. Default smime Function Bindings -9.13. Default mix Function Bindings -9.14. Default editor Function Bindings +9.2. Default Generic Menu Bindings +9.3. Default Index Menu Bindings +9.4. Default Pager Menu Bindings +9.5. Default Alias Menu Bindings +9.6. Default Query Menu Bindings +9.7. Default Attachment Menu Bindings +9.8. Default Compose Menu Bindings +9.9. Default Postpone Menu Bindings +9.10. Default Browser Menu Bindings +9.11. Default Pgp Menu Bindings +9.12. Default Smime Menu Bindings +9.13. Default Mixmaster Menu Bindings +9.14. Default Editor Menu Bindings List of Examples 3.1. Multiple configuration commands per line 3.2. Commenting configuration files -3.3. Escaping quotes in congfiguration files +3.3. Escaping quotes in configuration files 3.4. Splitting long configuration commands over several lines 3.5. Using external command's output in configuration files 3.6. Using environment variables in configuration files @@ -593,11 +606,13 @@ List of Examples 3.15. Using user-defined variables for config file readability 3.16. Using user-defined variables for backing up other config option values 3.17. Deferring user-defined variable expansion to runtime -3.18. Using external filters in format strings +3.18. Type conversions using variables +3.19. Using external filters in format strings 4.1. Matching all addresses in address lists 4.2. Using boolean operators in patterns -4.3. Specifying a default hook -5.1. Attachment counting +4.3. Specifying a ?default? hook +5.1. mime.types +5.2. Attachment counting 6.1. URLs 6.2. Managing multiple accounts @@ -610,7 +625,7 @@ Table of Contents 3. Getting Mutt 4. Mutt Online Resources 5. Contributing to Mutt -6. Typograhical Conventions +6. Typographical Conventions 7. Copyright Mutt is a small but very powerful text-based MIME mail client. Mutt is highly @@ -627,13 +642,11 @@ The official homepage can be found at http://www.mutt.org/. To subscribe to one of the following mailing lists, send a message with the word subscribe in the body to list-name-request@mutt.org. - * -- low traffic list for announcements + * ? low traffic list for announcements - * -- help, bug reports and feature requests + * ? help, bug reports and feature requests - * -- development mailing list - -Note + * ? development mailing list All messages posted to mutt-announce are automatically forwarded to mutt-users, so you do not need to be subscribed to both lists. @@ -678,7 +691,7 @@ continue to maintain stale translations. For contributing code patches for new features and bug fixes, please refer to the developer pages at http://dev.mutt.org/ for more details. -6. Typograhical Conventions +6. Typographical Conventions This section lists typographical conventions followed throughout this manual. See table Table 1.1, ?Typographical conventions for special terms? for @@ -815,7 +828,7 @@ messages or to limit the index to show only matching messages. Mutt supports a ?hook? concept which allows the user to execute arbitrary configuration commands and functions in certain situations such as entering a folder, starting a new message or replying to an existing one. These hooks can -be used to highly customize Mutt's behaviour including managing multiple +be used to highly customize Mutt's behavior including managing multiple identities, customizing the display for a folder or even implementing auto-archiving based on a per-folder basis and much more. @@ -834,7 +847,7 @@ emails, each with its number on the left, its flags (new email, important email, email that has been forwarded or replied to, tagged email, ...), the date when email was sent, its sender, the email size, and the subject. Additionally, the index also shows thread hierarchies: when you reply to an -email, and the other person replies back, you can see the other's person email +email, and the other person replies back, you can see the other person's email in a "sub-tree" below. This is especially useful for personal email between a group of people or when you've subscribed to mailing lists. @@ -937,7 +950,7 @@ Table 2.2. Most common navigation keys in page-based menus |----------------------+---------------+----------------------| |J or | |scroll down one line | |----------------------+---------------+----------------------| -| ||sroll up one line | +| ||scroll up one line | |----------------------+---------------+----------------------| |K, or | |move to the next page | |----------------------+---------------+----------------------| @@ -1159,6 +1172,10 @@ Table 2.5. Message status flags |! |message is flagged | |----+-------------------------------------------------------------| |* |message is tagged | +|----+-------------------------------------------------------------| +|n |thread contains new messages (only if collapsed) | +|----+-------------------------------------------------------------| +|o |thread contains old messages (only if collapsed) | +------------------------------------------------------------------+ @@ -1169,9 +1186,9 @@ Table 2.6. Message recipient flags |----+-------------------------------------------------| |+ |message is to you and you only | |----+-------------------------------------------------| -|T |message is to you, but also to or cc'ed to others| +|T |message is to you, but also to or CC'ed to others| |----+-------------------------------------------------| -|C |message is cc'ed to you | +|C |message is CC'ed to you | |----+-------------------------------------------------| |F |message is from you | |----+-------------------------------------------------| @@ -1181,8 +1198,8 @@ Table 2.6. Message recipient flags 5.2. The Pager -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 +By default, Mutt uses its built-in 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. @@ -1635,6 +1652,11 @@ generate a References: field, which allows you to create a new message thread, for example to create a new message to a mailing list without having to enter the mailing list's address. +If you intend to start a new thread by replying, please make really sure you +remove the In-Reply-To: header in your editor. Otherwise, though you'll produce +a technically valid reply, some netiquette guardians will be annoyed by this +so-called ?thread hijacking?. + 6.3. Sending Cryptographically Signed/Encrypted Messages If you have told Mutt to PGP or S/MIME encrypt a message, it will guide you @@ -1712,7 +1734,7 @@ outgoing messages if the $text_flowed variable is set, specifically it does not add the trailing spaces. After editing the initial message text and before entering the compose menu, -Mutt properly space-stuffes the message. Space-stuffing is required by RfC3676 +Mutt properly space-stuffs the message. Space-stuffing is required by RfC3676 defining format=flowed and means to prepend a space to: * all lines starting with a space @@ -1806,8 +1828,9 @@ Table of Contents 9. Using Color and Mono Video Attributes 10. Message Header Display - 10.1. Selecting Headers - 10.2. Ordering Displayed Headers + 10.1. Header Display + 10.2. Selecting Headers + 10.3. Ordering Displayed Headers 11. Alternative Addresses 12. Mailing Lists @@ -1829,6 +1852,7 @@ Table of Contents 26.1. Variable Types 26.2. Commands 26.3. User-Defined Variables + 26.4. Type Conversions 27. Reading Initialization Commands From Another File 28. Removing Hooks @@ -1895,7 +1919,7 @@ backticks are evaluated inside of double quotes, but not for single quotes. 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. -Example 3.3. Escaping quotes in congfiguration files +Example 3.3. Escaping quotes in configuration files set realname="Michael \"MuttDude\" Elkins" @@ -1974,21 +1998,45 @@ Usage: group [ -group name ...] { -rx expr ... | -addr expr ... } ungroup [ -group name ...] { * | -rx expr ... | -addr expr ... } -group is used to directly add either addresses or regular expressions to the -specified group or groups. The different categories of arguments to the group -command can be in any order. The flags -rx and -addr specify what the following -strings (that cannot begin with a hyphen) should be interpreted as: either a -regular expression or an email address, respectively. +Mutt supports grouping addresses logically into named groups. An address or +address pattern can appear in several groups at the same time. These groups can +be used in patterns (for searching, limiting and tagging) and in hooks by using +group patterns. This can be useful to classify mail and take certain actions +depending on in what groups the message is. For example, the mutt user's +mailing list would fit into the categories ?mailing list? and ?mutt-related?. +Using send-hook, the sender can be set to a dedicated one for writing mailing +list messages, and the signature could be set to a mutt-related one for writing +to a mutt list ? for other lists, the list sender setting still applies but a +different signature can be selected. Or, given a group only containing +recipients known to accept encrypted mail, ?auto-encryption? can be achieved +easily. + +The group command is used to directly add either addresses or regular +expressions to the specified group or groups. The different categories of +arguments to the group command can be in any order. The flags -rx and -addr +specify what the following strings (that cannot begin with a hyphen) should be +interpreted as: either a regular expression or an email address, respectively. These address groups can also be created implicitly by the alias, lists, -subscribe and alternates commands by specifying the optional -group option. +subscribe and alternates commands by specifying the optional -group option. For +example, -Once defined, these address groups can be used in patterns to search for and -limit the display to messages matching a group. +alternates -group me address1 address2 +alternates -group me -group work address3 + +would create a group named ?me? which contains all your addresses and a group +named ?work? which contains only your work address address3. Besides many other +possibilities, this could be used to automatically mark your own messages in a +mailing list folder as read or use a special signature for work-related +messages. -ungroup is used to remove addresses or regular expressions from the specified -group or groups. The syntax is similar to the group command, however the -special character * can be used to empty a group of all of its contents. +The ungroup command is used to remove addresses or regular expressions from the +specified group or groups. The syntax is similar to the group command, however +the special character * can be used to empty a group of all of its contents. As +soon as a group gets empty because all addresses and regular expressions have +been removed, it'll internally be removed, too (i.e. there cannot be an empty +group). When removing regular expressions from a group, the pattern must be +specified exactly as given to the group command or -group argument. 4. Defining/Using Aliases @@ -2020,7 +2068,7 @@ this file is sourced. Consequently, you can have multiple alias files, or you can have all aliases defined in your .muttrc. On the other hand, the function can use only one file, the one -pointed to by the $alias_file variable (which is ?/.muttrc by default). This +pointed to by the $alias_file variable (which is ~/.muttrc by default). This file is not special either, 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. @@ -2085,7 +2133,8 @@ browser editor - The editor is the line-based editor the user enters text data. + The editor is used to allow the user to enter a single line of text, such + as the To or Subject prompts in the compose menu. index @@ -2185,12 +2234,14 @@ Table 3.1. Symbolic key names +---------------------------------+ -key does not need to be enclosed in quotes unless it contains a space (???) or +key does not need to be enclosed in quotes unless it contains a space (? ?) or semi-colon (?;?). function specifies which action to take when key is pressed. For a complete -list of functions, see the reference. The special function unbinds the -specified key sequence. +list of functions, see the reference. Note that the bind expects function to be +specified without angle brackets. + +The special function unbinds the specified key sequence. 6. Defining Aliases for Character Sets @@ -2298,14 +2349,14 @@ specify both a foreground color and a background color (it is not possible to only specify one or the other). header and body match regexp in the header/body of a message, index matches -pattern (see Section 2, ?Patterns: Searching, Limiting and Tagging?) in the +pattern (see Section 3, ?Patterns: Searching, Limiting and Tagging?) in the message index. object can be one of: * attachment - * bold (hiliting bold patterns in the body of messages) + * bold (highlighting bold patterns in the body of messages) * error (error messages printed by Mutt) @@ -2323,17 +2374,17 @@ object can be one of: * quoted1, quoted2, ..., quotedN (higher levels of quoting) - * search (hiliting of words in the pager) + * search (highlighting of words in the pager) * signature * status (mode lines used to display info about the mailbox or message) - * tilde (the ??? used to pad blank lines in the pager) + * tilde (the ?~? used to pad blank lines in the pager) * tree (thread tree drawn in the message index and attachment menu) - * underline (hiliting underlined patterns in the body of messages) + * underline (highlighting underlined patterns in the body of messages) foreground and background can be one of the following: @@ -2381,7 +2432,7 @@ It 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 list of all entries. -Mutt also recognizes the keywords color0, color1, ?, colorN-1 (N being the +Mutt also recognizes the keywords color0, color1, ..., 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. @@ -2408,7 +2459,14 @@ For object, see the color command. attribute can be one of the following: 10. Message Header Display -10.1. Selecting Headers +10.1. Header Display + +When displaying a message in the pager, Mutt folds long header lines at $wrap +columns. Though there're precise rules about where to break and how, Mutt +always folds headers using a tab for readability. (Note that the sending side +is not affected by this, Mutt tries to implement standards compliant folding.) + +10.2. Selecting Headers Usage: @@ -2438,7 +2496,7 @@ unignore organization organisation x-mailer: x-newsreader: x-mailing-list: unignore posted-to: -10.2. Ordering Displayed Headers +10.3. Ordering Displayed Headers Usage: @@ -2506,9 +2564,9 @@ will be removed. Usage: lists [ -group name ...] regexp [ regexp ...] -unlists [ -group name ...] { * | regexp ... } +unlists { * | regexp ... } subscribe [ -group name ...] regexp [ regexp ...] -unsubscribe [ -group name ...] { * | regexp ... } +unsubscribe { * | regexp ... } 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, @@ -2527,7 +2585,7 @@ The Mail-Followup-To header is a non-standard extension which is not 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 since it's common practice on some mailing lists to send Cc upons +variable since it's common practice on some mailing lists to send Cc upon replies (which is more a group- than a list-reply). More precisely, Mutt maintains lists of patterns for the addresses of known and @@ -2541,8 +2599,7 @@ mail, for instance, you could say 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. +as it's often 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 @@ -2554,7 +2611,7 @@ 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. The -group flag adds all of the subsequent regular expressions to the named -group. +address group in addition to adding to the specified address list. The ?unlists? command is used to remove a token from the list of known and subscribed mailing-lists. Use ?unlists *? to remove all tokens. @@ -2593,8 +2650,8 @@ IMAP are described in Section 3, ?POP3 Support? and Section 4, ?IMAP Support? respectively. Mutt provides a number of advanced features for handling (possibly many) -folders and new mail within them, please refer to Section 9, ?Handling multiple -folders? for details (including in what situations and how often Mutt checks +folders and new mail within them, please refer to Section 10, ?New Mail +Detection? for details (including in what situations and how often Mutt checks for new mail). The ?unmailboxes? command is used to remove a token from the list of folders @@ -2605,23 +2662,10 @@ Note The folders in the mailboxes command are resolved when the command is executed, so if these names contain shortcut characters (such as ?=? and ?!?), any variable definition that affects these characters (like $folder and $spoolfile) -should be set before the mailboxes command. If none of these shorcuts are used, -a local path should be absolute as otherwise Mutt tries to find it relative to -the directory from where Mutt was started which may not always be desired. - -For Mbox and Mmdf folders, new mail is detected by comparing access and/or -modification times of files: Mutt assumes a folder has new mail if it wasn't -accessed after it was last modified. Utilities like biff or frm or any other -program which accesses the mailbox might cause Mutt to never detect new mail -for that mailbox if they do not properly reset the access time. Other possible -causes of Mutt not detecting new mail in these folders are backup tools -(updating access times) or filesystems mounted without access time update -support. - -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 which won't work for -size-neutral changes. +should be set before the mailboxes command. If none of these shortcuts are +used, a local path should be absolute as otherwise Mutt tries to find it +relative to the directory from where Mutt was started which may not always be +desired. 15. User-Defined Headers @@ -2759,7 +2803,7 @@ Note 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, similarily if $autoedit is set (as then the +cause any send-hook to be executed, similarly if $autoedit is set (as then the initial list of recipients is empty). Also note that 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. @@ -2817,6 +2861,21 @@ Example 3.13. Embedding push in folder-hook folder-hook . 'push ' +For using functions like shown in the example, it's important to use angle +brackets (??) to make Mutt recognize the input as a function name. +Otherwise it will simulate individual just keystrokes, i.e. ?push collapse-all? +would be interpreted as if you had typed ?c?, followed by ?o?, followed by ?l?, +..., which is not desired and may lead to very unexpected behavior. + +Keystrokes can be used, too, but are less portable because of potentially +changed key bindings. With default bindings, this is equivalent to the above +example: + +folder-hook . 'push \eV' + +because it simulates that Esc+V was pressed (which is the default binding of +). + 23. Executing Functions Usage: @@ -2824,7 +2883,7 @@ Usage: exec function [ function ...] This command can be used to execute any function. Functions are listed in the -function reference. ?execfunction? is equivalent to ?push ?. +function reference. ?exec function? is equivalent to ?push ?. 24. Message Scoring @@ -2836,7 +2895,7 @@ unscore { * | pattern ... } The score commands adds value to a message's score if pattern matches it. pattern is a string in the format described in the patterns section (note: For efficiency reasons, patterns which scan information not available in the index, -such as ?b, ?B or ?h, may not be used). value is a positive or negative +such as ~b, ~B or ~h, may not be used). value is a positive or negative integer. A message's final score is the sum total of all matching score entries. However, you may optionally prefix value with an equal sign (?=?) to cause evaluation to stop at a particular entry if there is a match. Negative @@ -2904,7 +2963,7 @@ 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 string that the ?H pattern-matching +$index_format variable. It's also the string that the ~H pattern-matching expression matches against for and functions. And it's what sorting by spam attribute will use as a sort key. @@ -2963,7 +3022,7 @@ string path A specialized string for representing paths including support for mailbox - shortcuts (see Section 7, ?Mailbox Shortcuts?) as well as tilde (???) for a + shortcuts (see Section 8, ?Mailbox Shortcuts?) as well as tilde (?~?) for a user's home directory and more. quadoption @@ -2978,7 +3037,7 @@ sort order regular expression - A regular expression, see Section 1, ?Regular Expressions? for an + A regular expression, see Section 2, ?Regular Expressions? for an introduction. folder magic @@ -3111,6 +3170,51 @@ macro pager "\ Note that there is a space between and the set configuration command, preventing Mutt from recording the macro's commands into its history. +26.4. Type Conversions + +Variables are always assigned string values which Mutt parses into its internal +representation according to the type of the variable, for example an integer +number for numeric types. For all queries (including $-expansion) the value is +converted from its internal type back into string. As a result, any variable +can be assigned any value given that its content is valid for the target. This +also counts for custom variables which are of type string. In case of parsing +errors, Mutt will print error messages. Example 3.18, ?Type conversions using +variables? demonstrates type conversions. + +Example 3.18. Type conversions using variables + +set my_lines = "5" # value is string "5" +set pager_index_lines = $my_lines # value is integer 5 + +set my_sort = "date-received" # value is string "date-received" +set sort = "last-$my_sort" # value is sort last-date-received + +set my_inc = $read_inc # value is string "10" (default of $read_inc) +set my_foo = $my_inc # value is string "10" + + +These assignments are all valid. If, however, the value of $my_lines would have +been ?five? (or something else that cannot be parsed into a number), the +assignment to $pager_index_lines would have produced an error message. + +Type conversion applies to all configuration commands which take arguments. But +please note that every expanded value of a variable is considered just a single +token. A working example is: + +set my_pattern = "~A" +set my_number = "10" + +# same as: score ~A +10 +score $my_pattern +$my_number + +What does not work is: + +set my_mx = "+mailbox1 +mailbox2" +mailboxes $my_mx +mailbox3 + +because the value of $my_mx is interpreted as a single mailbox named ?+mailbox1 ++mailbox2? and not two distinct mailboxes. + 27. Reading Initialization Commands From Another File Usage: @@ -3118,14 +3222,15 @@ Usage: source filename This command allows the inclusion of initialization commands from other files. -For example, I place all of my aliases in ?/.mail_aliases so that I can make my -?/.muttrc readable and keep my aliases private. +For example, I place all of my aliases in ~/.mail_aliases so that I can make my +~/.muttrc readable and keep my aliases private. -If the filename begins with a tilde (???), it will be expanded to the path of +If the filename begins with a tilde (?~?), it will be expanded to the path of your home directory. If the filename ends with a vertical bar (?|?), then filename is considered to -be an executable program from which to read input (eg. source ?/bin/myscript|). +be an executable program from which to read input (e.g. source ~/bin/myscript +|). 28. Removing Hooks @@ -3216,7 +3321,7 @@ a replacement format string including % expandos. All % expandos in a format string are expanded before the script is called so that: -Example 3.18. Using external filters in format strings +Example 3.19. Using external filters in format strings set status_format="script.sh '%r %f (%L)'|" @@ -3270,34 +3375,95 @@ Chapter 4. Advanced Usage Table of Contents -1. Regular Expressions -2. Patterns: Searching, Limiting and Tagging - - 2.1. Pattern Modifier - 2.2. Simple Searches - 2.3. Nesting and Boolean Operators - 2.4. Searching by Date - -3. Using Tags -4. Using Hooks - - 4.1. Message Matching in Hooks - -5. External Address Queries -6. Mailbox Formats -7. Mailbox Shortcuts -8. Handling Mailing Lists -9. Handling multiple folders -10. Editing Threads - - 10.1. Linking Threads - 10.2. Breaking Threads - -11. Delivery Status Notification (DSN) Support -12. Start a WWW Browser on URLs -13. Miscellany - -1. Regular Expressions +1. Character Set Handling +2. Regular Expressions +3. Patterns: Searching, Limiting and Tagging + + 3.1. Pattern Modifier + 3.2. Simple Searches + 3.3. Nesting and Boolean Operators + 3.4. Searching by Date + +4. Using Tags +5. Using Hooks + + 5.1. Message Matching in Hooks + +6. External Address Queries +7. Mailbox Formats +8. Mailbox Shortcuts +9. Handling Mailing Lists +10. New Mail Detection + + 10.1. How New Mail Detection Works + 10.2. Polling For New Mail + +11. Editing Threads + + 11.1. Linking Threads + 11.2. Breaking Threads + +12. Delivery Status Notification (DSN) Support +13. Start a WWW Browser on URLs +14. Miscellany + +1. Character Set Handling + +A ?character set? is basically a mapping between bytes and glyphs and implies a +certain character encoding scheme. For example, for the ISO 8859 family of +character sets, an encoding of 8bit per character is used. For the Unicode +character set, different character encodings may be used, UTF-8 being the most +popular. In UTF-8, a character is represented using a variable number of bytes +ranging from 1 to 4. + +Since Mutt is a command-line tool run from a shell, and delegates certain tasks +to external tools (such as an editor for composing/editing messages), all of +these tools need to agree on a character set and encoding. There exists no way +to reliably deduce the character set a plain text file has. Interoperability is +gained by the use of well-defined environment variables. The full set can be +printed by issuing locale on the command line. + +Upon startup, Mutt determines the character set on its own using routines that +inspect locale-specific environment variables. Therefore, it is generally not +necessary to set the $charset variable in Mutt. It may even be +counter-productive as Mutt uses system and library functions that derive the +character set themselves and on which Mutt has no influence. It's safest to let +Mutt work out the locale setup itself. + +If you happen to work with several character sets on a regular basis, it's +highly advisable to use Unicode and an UTF-8 locale. Unicode can represent +nearly all characters in a message at the same time. When not using a Unicode +locale, it may happen that you receive messages with characters not +representable in your locale. When displaying such a message, or replying to or +forwarding it, information may get lost possibly rendering the message unusable +(not only for you but also for the recipient, this breakage is not reversible +as lost information cannot be guessed). + +A Unicode locale makes all conversions superfluous which eliminates the risk of +conversion errors. It also eliminates potentially wrong expectations about the +character set between Mutt and external programs. + +The terminal emulator used also must be properly configured for the current +locale. Terminal emulators usually do not derive the locale from environment +variables, they need to be configured separately. If the terminal is +incorrectly configured, Mutt may display random and unexpected characters +(question marks, octal codes, or just random glyphs), format strings may not +work as expected, you may not be abled to enter non-ascii characters, and +possible more. Data is always represented using bytes and so a correct setup is +very important as to the machine, all character sets ?look? the same. + +Warning: A mismatch between what system and library functions think the locale +is and what Mutt was told what the locale is may make it behave badly with +non-ascii input: it will fail at seemingly random places. This warning is to be +taken seriously since not only local mail handling may suffer: sent messages +may carry wrong character set information the receiver has too deal with. The +need to set $charset directly in most cases points at terminal and environment +variable setup problems, not Mutt problems. + +A list of officially assigned and known character sets can be found at IANA, a +list of locally supported locales can be obtained by running locale -a. + +2. Regular Expressions All string patterns in Mutt including those in more complex patterns must be specified using regular expressions (regexp) in the ?POSIX extended? syntax @@ -3405,8 +3571,9 @@ Equivalence Classes 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 ???, ??? and ?e?. + the name ?e? might be used to represent all of ?e? with grave (???), ?e? + with acute (???) and ?e?. In this case, [[=e=]] is a regexp that matches + any of: ?e? with grave (???), ?e? with acute (???) and ?e?. A regular expression matching a single character may be followed by one of several repetition operators described in Table 4.2, ?Regular expression @@ -3479,9 +3646,9 @@ Table 4.3. GNU regular expression extensions Please note however that these operators are not defined by POSIX, so they may or may not be available in stock libraries on various systems. -2. Patterns: Searching, Limiting and Tagging +3. Patterns: Searching, Limiting and Tagging -2.1. Pattern Modifier +3.1. Pattern Modifier Many of Mutt's commands allow you to specify a pattern to match (limit, tag-pattern, delete-pattern, etc.). Table 4.4, ?Pattern modifiers? shows @@ -3603,7 +3770,7 @@ Table 4.4. Pattern modifiers +-----------------------------------------------------------------------------+ -Where EXPR is a regular expression. +Where EXPR is a regular expression, and GROUP is an address group. *) The forms ?<[MAX]?, ?>[MIN]?, ?[MIN]-? and ?-[MAX]? are allowed, too. @@ -3615,7 +3782,7 @@ 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 instead (?\\?). You can force Mutt to treat EXPR as a simple string -instead of a regular expression by using = instead of ? in the pattern name. +instead of a regular expression by using = instead of ~ in the pattern name. For example, =b *.* will find all messages that contain the literal string ?*.*?. Simple string matches are less powerful than regular expressions but can be considerably faster. This is especially true for IMAP folders, because @@ -3635,12 +3802,12 @@ Example 4.1. Matching all addresses in address lists ^~C \.de$ -2.2. Simple Searches +3.2. Simple Searches 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 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 +characters: ?~?, ?=? or ?%?). If the query is supposed to contain one of these special characters, they must be escaped by prepending a backslash (?\?). The first type is by checking whether the query string equals a keyword @@ -3684,7 +3851,7 @@ The second type of simple search is to build a complex search pattern using $simple_search as a template. Mutt will insert your query properly quoted and search for the composed complex query. -2.3. Nesting and Boolean Operators +3.3. Nesting and Boolean Operators Logical AND is performed by specifying more than one criterion. For example: @@ -3711,11 +3878,12 @@ Example 4.2. Using boolean operators in patterns !(~t mutt|~c mutt) ~f elkins -Here is an example using white space in the regular expression (note the ' and -" delimiters). For this to match, the mail's subject must match the ?^Junk -+From +Me$? and it must be from either ?Jim +Somebody? or ?Ed +SomeoneElse?: +Here is an example using white space in the regular expression (note the ?'? +and ?"? delimiters). For this to match, the mail's subject must match the ?^ +Junk +From +Me$? and it must be from either ?Jim +Somebody? or ?Ed ++SomeoneElse?: - '~s "^Junk +From +Me$" ~f ("Jim +Somebody"|"Ed +SomeoneElse")' +'~s "^Junk +From +Me$" ~f ("Jim +Somebody"|"Ed +SomeoneElse")' Note @@ -3723,14 +3891,14 @@ If a regular expression contains parenthesis, or a vertical bar ("|"), 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 +end. This would be separated to two OR'd patterns: ~f me@(mutt\.org and cs\.hmc \.edu). They are never what you want. -2.4. Searching by Date +3.4. Searching by Date Mutt supports two types of dates, absolute and relative. -2.4.1. Absolute Dates +3.4.1. Absolute Dates 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: @@ -3768,7 +3936,7 @@ the following pattern: Limit to messages matching: ~d 15/1/2001*2w -2.4.2. Relative Dates +3.4.2. Relative Dates This type of date is relative to the current date, and may be specified as: @@ -3791,7 +3959,7 @@ 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 in the main index. -3. Using Tags +4. Using Tags Sometimes it is desirable to perform an operation on a group of messages all at once rather than one at a time. An example might be to save messages to a @@ -3814,7 +3982,7 @@ it's execution. Mutt will stop ?eating? the macro when it encounters the operator; after this operator the rest of the macro will be executed as normal. -4. Using Hooks +5. Using Hooks A hook is a concept found in many other programs which allows you to execute arbitrary commands before performing some operation. For example, you may wish @@ -3863,11 +4031,11 @@ send-hook . 'unmy_hdr From:' send-hook ~C'^b@b\.b$' my_hdr from: c@c.c -In Example 4.3, ?Specifying a default hook?, by default the value of $from and -$realname is not overridden. When sending messages either To: or Cc: to +In Example 4.3, ?Specifying a ?default? hook?, by default the value of $from +and $realname is not overridden. When sending messages either To: or Cc: to , the From: header is changed to . -4.1. Message Matching in Hooks +5.1. Message Matching in Hooks Hooks that act upon messages (message-hook, reply-hook, send-hook, send2-hook, save-hook, fcc-hook) are evaluated in a slightly different manner. For the @@ -3895,14 +4063,14 @@ language, using the translation specified by the $default_hook variable. The pattern is translated at the time the hook is declared, so the value of $default_hook that is in effect at that time will be used. -5. External Address Queries +6. External Address Queries Mutt supports connecting to external directory databases such as LDAP, ph/qi, bbdb, or NIS through a wrapper script which connects to Mutt using a simple interface. Using the $query_command variable, you specify the wrapper command to use. For example: -set query_command = "mutt_ldap_query.pl '%s'" +set query_command = "mutt_ldap_query.pl %s" The wrapper script should accept the query on the command-line. It should return a one line message, then each matching response on a single line, each @@ -3933,10 +4101,10 @@ Mutt will expand the address in place. If there are multiple responses, Mutt will activate the query menu. At the query menu, you can select one or more addresses to be added to the prompt. -6. Mailbox Formats +7. Mailbox Formats Mutt supports reading and writing of four different local mailbox formats: -mbox, MMDF, MH and Maildir. The mailbox type is autodetected, so there is no +mbox, MMDF, MH and Maildir. The mailbox type is auto detected, so there is no need to use a flag for different mailbox types. When creating new mailboxes, Mutt uses the default specified with the $mbox_type variable. A short description of the formats follows. @@ -3953,9 +4121,9 @@ the environment, new mail detection can be unreliable. Mbox folders are fast to open and easy to archive. MMDF. This is a variant of the mbox format. Each message is surrounded by lines -containing ?^A^A^A^A? (four control-A's). The same problems as for mbox apply -(also with finding the right message separator as four control-A's may appear -in message bodies). +containing ?^A^A^A^A? (four times control-A's). The same problems as for mbox +apply (also with finding the right message separator as four control-A's may +appear in message bodies). MH. A radical departure from mbox and MMDF, a mailbox consists of a directory and each message is stored in a separate file. The filename indicates the @@ -3981,36 +4149,42 @@ files are used for metadata (which is embedded in the message filenames) and Maildir is locking-free, it's easy to sync across different machines using file-level synchronization tools. -7. Mailbox Shortcuts +8. Mailbox Shortcuts 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 or in path-related configuration variables. Note that these only work at the beginning of a string. - * ! ? refers to your $spoolfile (incoming) mailbox - - * > ? refers to your $mbox file +Table 4.7. Mailbox shortcuts - * < ? refers to your $record file - - * ^ ? refers to the current mailbox - - * - or !! ? refers to the file you've last visited - - * ? ? refers to your home directory - - * = or + ? refers to your $folder directory ++-----------------------------------------------------------------------------+ +|Shortcut| Refers to... | +|--------+--------------------------------------------------------------------| +|! |your $spoolfile (incoming) mailbox | +|--------+--------------------------------------------------------------------| +|> |your $mbox file | +|--------+--------------------------------------------------------------------| +|< |your $record file | +|--------+--------------------------------------------------------------------| +|^ |the current mailbox | +|--------+--------------------------------------------------------------------| +|- or !! |the file you've last visited | +|--------+--------------------------------------------------------------------| +|~ |your home directory | +|--------+--------------------------------------------------------------------| +|= or + |your $folder directory | +|--------+--------------------------------------------------------------------| +|@alias |to the default save folder as determined by the address of the alias| ++-----------------------------------------------------------------------------+ - * @alias ? refers to the default save folder as determined by the address of - the alias 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=^' -8. Handling Mailing Lists +9. Handling Mailing Lists Mutt has a few configuration options that make dealing with large amounts of mail easier. The first thing you must do is to let Mutt know what addresses you @@ -4070,7 +4244,7 @@ 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? 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 +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 and other mail filtering agents. @@ -4082,12 +4256,48 @@ the same concept. It makes dealing with large volume mailing lists easier because you can easily delete uninteresting threads and quickly find topics of value. -9. Handling multiple folders +10. New Mail Detection Mutt supports setups with multiple folders, allowing all of them to be monitored for new mail (see Section 14, ?Monitoring Incoming Mail? for details). +10.1. How New Mail Detection Works + +For Mbox and Mmdf folders, new mail is detected by comparing access and/or +modification times of files: Mutt assumes a folder has new mail if it wasn't +accessed after it was last modified. Utilities like biff or frm or any other +program which accesses the mailbox might cause Mutt to never detect new mail +for that mailbox if they do not properly reset the access time. Other possible +causes of Mutt not detecting new mail in these folders are backup tools +(updating access times) or filesystems mounted without access time update +support (for Linux systems, see the relatime option). + +Note + +Contrary to older Mutt releases, it now maintains the new mail status of a +folder by properly resetting the access time if the folder contains at least +one message which is neither read, nor deleted, nor marked as old. + +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 which won't work for +size-neutral changes. + +New mail for Maildir is assumed if there is one message in the new/ +subdirectory which is not marked deleted (see $maildir_trash). For MH folders, +a mailbox is considered having new mail if there's at least one message in the +?unseen? sequence as specified by $mh_seq_unseen. + +Mutt does not poll POP3 folders for new mail, it only periodically checks the +currently opened folder (if it's a POP3 folder). + +For IMAP, by default Mutt uses recent message counts provided by the server to +detect new mail. If the $imap_idle option is set, it'll use the IMAP IDLE +extension if advertised by the server. + +10.2. Polling For New Mail + When in the index menu and being idle (also see $timeout), Mutt periodically checks for new mail in all folders which have been configured via the mailboxes command. The interval depends on the folder type: for local/IMAP folders it @@ -4107,17 +4317,19 @@ For the index, by default Mutt displays the number of mailboxes with new mail in the status bar, please refer to the $status_format variable for details. When changing folders, Mutt fills the prompt with the first folder from the -mailboxes list containing new mail (if any), pressing space will cycle through -folders with new mail. +mailboxes list containing new mail (if any), pressing will cycle +through folders with new mail. The (by default unbound) function + in the index can be used to immediately open the next +folder with unread mail (if any). -10. Editing Threads +11. Editing Threads 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 from these annoyances which make it hard to follow a discussion. -10.1. Linking Threads +11.1. 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 @@ -4127,9 +4339,9 @@ message and using the function (bound to & by default). The reply will then be connected to this parent message. You can also connect multiple children at once, tagging them and using the - command (';') or the $auto_tag option. + command (?;?) or the $auto_tag option. -10.2. Breaking Threads +11.2. Breaking Threads 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 the subject to a @@ -4137,7 +4349,7 @@ totally unrelated one. You can fix such threads by using the function (bound by default to #), which will turn the subthread starting from the current message into a whole different thread. -11. Delivery Status Notification (DSN) Support +12. Delivery Status Notification (DSN) Support RFC1894 defines a set of MIME content types for relaying information about the status of electronic mail messages. These can be thought of as ?return @@ -4157,7 +4369,7 @@ consider your MTA documentation whether DSN is supported. For SMTP delivery using $smtp_url, it depends on the capabilities announced by the server whether Mutt will attempt to request DSN or not. -12. Start a WWW Browser on URLs +13. Start a WWW Browser on URLs If a message contains URLs, it is efficient to get a menu with all the URLs and start a WWW browser on one of them. This functionality is provided by the @@ -4167,7 +4379,7 @@ contrib/ and the configuration commands: macro index \cb |urlview\n macro pager \cb |urlview\n -13. Miscellany +14. Miscellany This section documents various features that fit nowhere else. @@ -4196,9 +4408,10 @@ Table of Contents 1. Using MIME in Mutt - 1.1. Viewing MIME Messages in the Pager - 1.2. The Attachment Menu - 1.3. The Compose Menu + 1.1. MIME Overview + 1.2. Viewing MIME Messages in the Pager + 1.3. The Attachment Menu + 1.4. The Compose Menu 2. MIME Type Configuration with mime.types 3. MIME Viewer Configuration with Mailcap @@ -4224,16 +4437,48 @@ types. 1. Using MIME in Mutt -There are three areas/menus in Mutt which deal with MIME, they are the pager -(while viewing a message), the attachment menu and the compose menu. - -1.1. Viewing MIME Messages in the Pager +1.1. MIME Overview + +MIME is short for ?Multipurpose Internet Mail Extension? and describes +mechanisms to internationalize and structure mail messages. Before the +introduction of MIME, messages had a single text part and were limited to +us-ascii header and content. With MIME, messages can have attachments (and even +attachments which itself have attachments and thus form a tree structure), +nearly arbitrary characters can be used for sender names, recipients and +subjects. + +Besides the handling of non-ascii characters in message headers, to Mutt the +most important aspect of MIME are so-called MIME types. These are constructed +using a major and minor type separated by a forward slash. These specify +details about the content that follows. Based upon these, Mutt decides how to +handle this part. The most popular major type is ?text? with minor types for +plain text, HTML and various other formats. Major types also exist for images, +audio, video and of course general application data (e.g. to separate +cryptographically signed data with a signature, send office documents, and in +general arbitrary binary data). There's also the multipart major type which +represents the root of a subtree of MIME parts. A list of supported MIME types +can be found in Table 5.1, ?Supported MIME types?. + +MIME also defines a set of encoding schemes for transporting MIME content over +the network: 7bit, 8bit, quoted-printable, base64 and binary. There're some +rules when to choose what for encoding headers and/or body (if needed), and +Mutt will in general make a good choice. + +Mutt does most of MIME encoding/decoding behind the scenes to form messages +conforming to MIME on the sending side. On reception, it can be flexibly +configured as to how what MIME structure is displayed (and if it's displayed): +these decisions are based on the content's MIME type. There are three areas/ +menus in dealing with MIME: the pager (while viewing a message), the attachment +menu and the compose menu. + +1.2. Viewing MIME Messages in the Pager When you select a message from the index and view it in the pager, Mutt decodes -the message to a text representation. Mutt internally supports a number of MIME -types, including text/plain, text/enriched, message/rfc822, and message/news. -In addition, the export controlled version of Mutt recognizes a variety of PGP -MIME types, including PGP/MIME and application/pgp. +as much of a message as possible to a text representation. Mutt internally +supports a number of MIME types, including the text major type (with all minor +types), the message/rfc822 (mail messages) type and some multipart types. In +addition, it recognizes a variety of PGP MIME types, including PGP/MIME and +application/pgp. Mutt will denote attachments with a couple lines describing them. These lines are of the form: @@ -4242,13 +4487,13 @@ are of the form: [-- Type: text/plain, Encoding: 7bit, Size: 10000 --] Where the Description is the description or filename given for the attachment, -and the Encoding is one of 7bit/8bit/quoted-printable/base64/binary. +and the Encoding is one of the already mentioned content encodings. If Mutt cannot deal with a MIME type, it will display a message like: [-- image/gif is unsupported (use 'v' to view this part) --] -1.2. The Attachment Menu +1.3. The Attachment Menu The default binding for is ?v?, which displays the attachment menu for a message. The attachment menu displays a list of the @@ -4258,15 +4503,16 @@ attachments at once, by tagging the attachments and by using the 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. +definition (the mailcap mechanism is explained later in detail). Finally, you can apply the usual message-related functions (like , and the and functions) to attachments of type message/rfc822. -See the help on the attachment menu for more information. +See table Table 9.7, ?Default Attachment Menu Bindings? for all available +functions. -1.3. The Compose Menu +1.4. The Compose Menu The compose menu is the menu you see before you send a message. It allows you to edit the recipient list, the subject, and other aspects of your message. It @@ -4276,12 +4522,12 @@ and rename an attachment or a list of tagged attachments. You can also modifying the attachment information, notably the type, encoding and description. -Attachments appear as follows: +Attachments appear as follows by default: - 1 [text/plain, 7bit, 1K] /tmp/mutt-euler-8082-0 2 [applica/x-gunzip, base64, 422K] ~/src/mutt-0.85.tar.gz -The '-' denotes that Mutt will delete the file after sending (or postponing, or +The ?-? denotes that Mutt will delete the file after sending (or postponing, or canceling) the message. It can be toggled with the command (default: u). The next field is the MIME content-type, and can be changed with the command (default: ^T). The next field is the encoding for the @@ -4291,52 +4537,86 @@ 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 command (default: R). The final field is the description of the attachment, and can be changed with the command (default: -d). +d). See $attach_format for a full list of available expandos to format this +display to your needs. 2. MIME Type Configuration with mime.types +To get most out of MIME, it's important that a MIME part's content type matches +the content as closely as possible so that the recipient's client can +automatically select the right viewer for the content. However, there's no +reliable for Mutt to know how to detect every possible file type. Instead, it +uses a simple plain text mapping file that specifies what file extension +corresponds to what MIME type. This file is called mime.types. + 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 /etc/mime.types +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 + +Each line starts with the full MIME type, followed by a space and +space-separated list of file extensions. For example you could use: -The mime.types file consist of lines containing a MIME type and a space -separated list of extensions. For example: +Example 5.1. mime.types application/postscript ps eps application/pgp pgp audio/x-aiff aif aifc aiff + A sample mime.types file comes with the Mutt distribution, and should contain most of the MIME types you are likely to use. -If Mutt can not determine the mime type by the extension of the file you +If Mutt can not determine the MIME type by the extension of the file you 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 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 -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 if the -recipient of the message is likely to be expecting such attachments. +by using the command from the compose menu (default: ^T), see +Table 5.1, ?Supported MIME types? for supported major types. Mutt recognizes +all of these if the appropriate entry is found in the mime.types file. +Non-recognized mime types should only be used if the recipient of the message +is likely to be expecting such attachments. + +Table 5.1. Supported MIME types + ++------------------------------------------------------------------+ +|MIME major type|Standard| Description | +|---------------+--------+-----------------------------------------| +|application |yes |General application data | +|---------------+--------+-----------------------------------------| +|audio |yes |Audio data | +|---------------+--------+-----------------------------------------| +|image |yes |Image data | +|---------------+--------+-----------------------------------------| +|message |yes |Mail messages, message status information| +|---------------+--------+-----------------------------------------| +|model |yes |VRML and other modeling data | +|---------------+--------+-----------------------------------------| +|multipart |yes |Container for other MIME parts | +|---------------+--------+-----------------------------------------| +|text |yes |Text data | +|---------------+--------+-----------------------------------------| +|video |yes |Video data | +|---------------+--------+-----------------------------------------| +|chemical |no |Mostly molecular data | ++------------------------------------------------------------------+ + + +MIME types are not arbitrary, they need to be assigned by IANA. 3. MIME Viewer Configuration with Mailcap Mutt supports RFC 1524 MIME Configuration, in particular the Unix specific format specified in Appendix A of RFC 1524. This file format is commonly -referred to as the mailcap format. Many MIME compliant programs utilize the +referred to as the ?mailcap? format. Many MIME compliant programs utilize the mailcap format, allowing you to specify handling for all MIME types in one place for all programs. Programs known to use this format include Firefox, lynx and metamail. -In order to handle various MIME types that Mutt can not handle internally, Mutt -parses a series of external configuration files to find an external handler. -The default search string for these files is a colon delimited list containing -the following files: +In order to handle various MIME types that Mutt doesn't have built-in support +for, it parses a series of external configuration files to find an external +handler. The default search string for these files is a colon delimited list +containing the following files: 1. $HOME/.mailcap @@ -4371,14 +4651,14 @@ A comment line consists of a # character followed by anything you want. A blank line is blank. A definition line consists of a content type, a view command, and any number of -optional fields. Each field of a definition line is divided by a semicolon ';' +optional fields. Each field of a definition line is divided by a semicolon ?;? character. -The content type is specified in the MIME standard type/subtype method. For +The content type is specified in the MIME standard ?type/subtype? notation. For example, text/plain, text/html, image/gif, etc. In addition, the mailcap format -includes two formats for wildcards, one using the special '*' subtype, the +includes two formats for wildcards, one using the special ?*? subtype, the other is the implicit wild, where you only include the major type. For example, -image/*, or video, will match all image types and video types, respectively. +image/*, or video will match all image types and video types, respectively. The view command is a Unix command for viewing the type specified. There are two different types of commands supported. The default is to send the body of @@ -4387,10 +4667,13 @@ the MIME message to the command on stdin. You can change this behavior by using of the MIME message to a temporary file, and then call the view command with the %s replaced by the name of the temporary file. In both cases, Mutt will turn over the terminal to the view program until the program quits, at which -time Mutt will remove the temporary file if it exists. +time Mutt will remove the temporary file if it exists. This means that mailcap +does not work out of the box with programs which detach themselves from the +terminal right after starting, like open on Mac OS X. In order to nevertheless +use these programs with mailcap, you probably need custom shell scripts. So, in the simplest form, you can send a text/plain message to the external -pager more on stdin: +pager more on standard input: text/plain; more @@ -4402,8 +4685,8 @@ Perhaps you would like to use lynx to interactively view a text/html message: text/html; lynx %s -In this case, lynx does not support viewing a file from stdin, so you must use -the %s syntax. +In this case, lynx does not support viewing a file from standard input, so you +must use the %s syntax. Note @@ -4422,8 +4705,6 @@ text formats, then you would use the following: text/html; lynx %s text/*; more -This is the simplest form of a mailcap file. - 3.2. Secure Use of Mailcap The interpretation of shell meta-characters embedded in MIME parameters can @@ -4438,8 +4719,8 @@ Therefore you should pay attention to the following rules: Keep the %-expandos away from shell quoting. Don't quote them with single or double quotes. Mutt does this for you, the right way, as should any other program which interprets mailcap. Don't put them into backtick expansions. Be -highly careful with eval statements, and avoid them if possible at all. Trying -to fix broken behavior with quotes introduces new leaks - there is no +highly careful with evil statements, and avoid them if possible at all. Trying +to fix broken behavior with quotes introduces new leaks ? there is no alternative to correct quoting in the first place. If you have to use the %-expandos' values in context where you need quoting or @@ -4456,23 +4737,27 @@ text/test-mailcap-bug; cat %s; copiousoutput; test=charset=%{charset} \ 3.3.1. Optional Fields In addition to the required content-type and view command fields, you can add -semi-colon ';' separated fields to set flags and other options. Mutt recognizes +semi-colon ?;? separated fields to set flags and other options. Mutt recognizes the following optional fields: copiousoutput This flag tells Mutt that the command passes possibly large amounts of text - on stdout. This causes Mutt to invoke a pager (either the internal pager or - the external pager defined by the pager variable) on the output of the view - command. Without this flag, Mutt assumes that the command is interactive. - One could use this to replace the pipe to more in the lynx -dump example in - the Basic section: + on standard output. This causes Mutt to invoke a pager (either the internal + pager or the external pager defined by the pager variable) on the output of + the view command. Without this flag, Mutt assumes that the command is + interactive. One could use this to replace the pipe to more in the lynx + -dump example in the Basic section: text/html; lynx -dump %s ; copiousoutput This will cause lynx to format the text/html output as text/plain and Mutt will use your standard pager to display the results. + Note that when using the built-in pager, only entries with this flag will + be considered a handler for a MIME type ? all other entries will be + ignored. + needsterminal Mutt uses this flag when viewing attachments with auto_view, in order to @@ -4505,7 +4790,7 @@ edit= This flag specifies the command to use to edit a specific MIME type. Mutt supports this from the compose menu, and also uses it to compose new - attachments. Mutt will default to the defined editor for text attachments. + attachments. Mutt will default to the defined $editor for text attachments. nametemplate=