From 53748015390b67c5a6f9d3cfeab279c8a4a951a6 Mon Sep 17 00:00:00 2001 From: Rocco Rutte Date: Wed, 10 Dec 2008 15:39:31 +0100 Subject: [PATCH] Manual: Wrap important notes in --- ChangeLog | 17 +++++ doc/manual.xml.head | 175 ++++++++++++++++++++++++++++++++++---------- doc/mutt.css | 5 +- 3 files changed, 157 insertions(+), 40 deletions(-) diff --git a/ChangeLog b/ChangeLog index 35d1a6d4..8cc7f304 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,20 @@ +2008-12-10 15:36 +0100 Rocco Rutte (ca2eee8d763e) + + * doc/Makefile.am, doc/chunk.xsl, doc/html.xsl, doc/mutt.xsl: Move + common XSLT params to mutt.xsl imported into (chunk|html).xsl + +2008-12-10 13:58 +0100 Rocco Rutte (11200e1a8b84) + + * ChangeLog, doc/gen-map-doc, doc/makedoc.c, doc/manual.xml.head, + doc/manual.xml.tail, init.h: Manual: Only wrap real text paragraphs + in + + Elements such as lists, tables, synopsis don't need it and produce + hundreds of warnings in tidy because of empty paragraphs. + + With this change, the manual should be fully XHTML 1.0 Transitional + and validate without warnings and errors. + 2008-12-10 13:58 +0100 Rocco Rutte (c1873847c50e) * hg-commit: hg-commit: Work even in subdirectories diff --git a/doc/manual.xml.head b/doc/manual.xml.head index f6fac9b6..ed701ccb 100644 --- a/doc/manual.xml.head +++ b/doc/manual.xml.head @@ -70,12 +70,14 @@ word subscribe in the body to + -Note: all messages posted to +All messages posted to mutt-announce are automatically forwarded to mutt-users, so you do not need to be subscribed to both lists. + @@ -612,12 +614,19 @@ where Ps can be one of the codes shown in Mutt uses these attributes for handling text/enriched messages, and they can also be used by an external -autoview script for highlighting purposes. -Note: If you change the colors for your +autoview script for highlighting +purposes. + + + + +If you change the colors for your display, for example by changing the color associated with color2 for 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 @@ -626,6 +635,7 @@ 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. + @@ -663,14 +673,16 @@ as shown in . + -Note: Collapsing a thread displays only the first message +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. + See also: $strict_threads. @@ -696,10 +708,17 @@ menus have these interesting functions: Creates a new alias based upon the current message (or prompts for a new one). Once editing is complete, an alias -command is added to the file specified by the $alias_file variable for future use. Note: +command is added to the file specified by +the $alias_file variable +for future use + + + + Mutt does not read the $alias_file upon startup so you must explicitly source the file. + @@ -1005,12 +1024,18 @@ message. The compose menu is also used to edit the attachments for a message which can be either files or other messages. The <attach-message> function to will prompt you for a folder to attach messages from. You can now tag messages in that folder and they -will be attached to the message you are sending. Note that certain +will be attached to the message you are sending. + + + + +Note that certain operations like composing a new mail, replying, forwarding, etc. are not permitted when you are in that folder. The %r in $status_format will change to a A to indicate that you are in attach-message mode. + @@ -1264,13 +1289,15 @@ followed by space is not intended to be a quote character + -Note that mutt only support space-stuffing +Mutt only supports space-stuffing for the first two types of lines but not for the third: It is impossible to safely detect whether a leading > character starts a quote or not. Furthermore, Mutt only applies space-stuffing once after the initial edit is finished. + All leading spaces are to be removed by receiving clients to restore @@ -1365,12 +1392,14 @@ messages exist. If multiple messages are currently postponed, the like to resume. + -Note: If you postpone a reply to a message, the reply setting of +If you postpone a reply to a message, the reply setting of the message is only updated when you actually finish the message and send it. Also, you must be in the same folder with the message you replied to for the status of the message to be updated. + See also the $postpone quad-option. @@ -1500,9 +1529,15 @@ my_hdr X-Operating-System: `uname -a` The output of the Unix command uname -a will be substituted before the -line is parsed. Note that since initialization files are line oriented, only +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 @@ -1676,10 +1711,12 @@ you are communicating with. Mutt allows you to create aliases wh a short string to a full address. + -Note: if you want to create an alias for more than +If you want to create an alias for more than one address, you must separate the addresses with a comma (,). + The optional -group argument to @@ -2011,17 +2048,21 @@ matches multiple folder-hook's, they are executed in the order given in the muttrc. + -Note: if you use the ! shortcut for $spoolfile at the beginning of the pattern, you must place it +If you use the ! shortcut for $spoolfile at the beginning of the pattern, you must place it inside of double or single quotes in order to distinguish it from the logical not operator for the expression. + + -Note that the settings are not restored when you leave the mailbox. +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 @@ -2108,10 +2149,12 @@ Optionally you can specify a descriptive text after sequence + -Note: Macro definitions (if any) listed in the help screen(s), are +Macro definitions (if any) listed in the help screen(s), are silently truncated at the screen width, and are not wrapped. + @@ -2256,18 +2299,22 @@ set COLORFGBG="green;black" export COLORFGBG + -Note: The S-Lang library requires you to use the lightgray +The S-Lang library requires you to use the lightgray and brown keywords instead of white and yellow when setting this variable. + + -Note: The uncolor command can be applied to the index object only. It +The uncolor command can be applied to the index object only. 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 index list of all entries. + Mutt also recognizes the keywords color0, color1, …, @@ -2633,12 +2680,19 @@ 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. 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. Note that -the Mail-Followup-To header is a non-standard extension which is not +not to send copies of replies to your personal address. + + + + +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. +of the Mail-Followup-To header is controlled by the +$followup_to +configuration variable. + More precisely, Mutt maintains lists of patterns for the addresses @@ -2772,8 +2826,9 @@ of folders which receive mail. Use unmailboxes * to remove all tokens. + -Note: the folders in the mailboxes command are resolved when +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 @@ -2781,6 +2836,7 @@ 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 @@ -2848,11 +2904,13 @@ my_hdr Organization: A Really Big Company, Anytown, USA in your .muttrc. + -Note: space characters are not allowed between the keyword and +Space characters are not allowed between the keyword and the colon (:). The standard for electronic mail (RFC2822) says that space is illegal there, so Mutt enforces the rule. + If you would like to add a header field to a single message, you should @@ -3042,10 +3100,16 @@ is executed when pattern matches. reply-hook is matched against the message you are replying to, instead of the message you are sending. send-hook is -matched against all messages, both new and replies. Note: +matched against all messages, both new +and replies. + + + + reply-hooks are matched before the send-hook, regardless of the order specified in the user's configuration file. + send2-hook is matched every time a message is changed, either @@ -3072,14 +3136,16 @@ variables in order to change the language of the attributions and signatures based upon the recipients. + -Note: the 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 subject, don't have any effect on the current message when executed from a send-hook. + @@ -3825,10 +3891,16 @@ convenience, we have included below a brief description of this syntax. The search is case sensitive if the pattern contains at least one upper -case letter, and case insensitive otherwise. Note that \ +case letter, and case insensitive otherwise. + + + + +Note that \ must be quoted if used for a regular expression in an initialization command: \\. + A regular expression is a pattern that describes a set of strings. @@ -3836,6 +3908,7 @@ Regular expressions are constructed analogously to arithmetic expressions, by using various operators to combine smaller expressions. + Note that the regular expression can be enclosed/delimited by either " or ' which is useful if the regular expression includes a white-space @@ -3843,6 +3916,7 @@ character. See for more information on " and ' delimiter processing. To match a literal " or ' you must preface it with \ (backslash). + The fundamental building blocks are the regular expressions that match @@ -3902,12 +3976,18 @@ The following classes are defined by the POSIX standard in A character class is only valid in a regular expression inside the -brackets of a character list. Note that the brackets in these +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 +in addition to the brackets delimiting the bracket list. For example, [[:digit:]] is equivalent to [0-9]. + Two additional special sequences can appear in character lists. These @@ -3987,10 +4067,12 @@ precedence over alternation. A whole subexpression may be enclosed in parentheses to override these precedence rules. + -Note: If you compile Mutt with the GNU rx package, the +If you compile Mutt with the GNU rx package, the following operators may also be used in regular expressions as described in . + GNU regular expression extensions @@ -4119,6 +4201,7 @@ are allowed, too. Pattern Modifier + Note that patterns matching 'lists' of addresses (notably c, C, p, P and t) match if there is at least one match in the whole list. If you want to @@ -4126,6 +4209,7 @@ make sure that all elements of that list match, you need to prefix your pattern with ˆ. This example matches all mails which only has recipients from Germany. + ^~C \.de$ @@ -4257,16 +4341,14 @@ or Ed +SomeoneElse: '~s "^Junk +From +Me$" ~f ("Jim +Somebody"|"Ed +SomeoneElse")' + -Note that if a regular expression contains parenthesis, or a vertical bar +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, +pattern language. For example: ~f "me@(mutt\.org|cs\.hmc\.edu)" - - -~f "me@(mutt\.org|cs\.hmc\.edu)" - + Without the quotes, the parenthesis wouldn't end. @@ -4371,12 +4453,14 @@ Example: to select messages less than 1 month old, you would use Limit to messages matching: ~d <1m + -Note: all dates used when searching are relative to the +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. + @@ -4479,13 +4563,15 @@ configuration option/command. See for specific details on each type of hook available. + -Note: if a hook changes configuration settings, these changes remain +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: + Combining <literal>send-hook</literal> and <literal>my_hdr</literal> @@ -4637,7 +4723,7 @@ surrounded by lines containing ˆAˆAˆAˆA (four consists of a directory and each message is stored in a separate file. The filename indicates the message number (however, this is may not correspond to the message number Mutt displays). Deleted messages are -renamed with a comma (,) prepended to the filename. Note: Mutt +renamed with a comma (,) prepended to the filename. Mutt detects this type of mailbox by looking for either .mh_sequences or .xmhcache (needed to distinguish normal directories from MH mailboxes). @@ -4772,11 +4858,13 @@ that the reply goes to the mailing list, even if it's not specified in the list of recipients in the Mail-Followup-To. + -Note that, when header editing is enabled, you can create a +When header editing is enabled, you can create a Mail-Followup-To header manually. Mutt will only auto-generate this header if it doesn't exist when you send the message. + The other method some mailing list admins use is to generate a @@ -5269,11 +5357,16 @@ text/html; lynx %s In this case, lynx does not support viewing a file from stdin, so you must use the %s syntax. -Note: Some older versions of lynx contain a bug where they + + + + +Some older versions of lynx contain a bug where they will check the mailcap file for a viewer for text/html. They will find the line which calls lynx, and run it. This causes lynx to continuously spawn itself to view the object. + On the other hand, maybe you don't want to use lynx interactively, you @@ -5461,7 +5554,7 @@ entry should be used. The command is defined with the command expansion rules defined in the next section. If the command returns 0, then the test passed, and Mutt uses this entry. If the command returns non-zero, then the test failed, and Mutt continues searching for the right entry. -Note: the content-type must match before Mutt performs the test. +Note that the content-type must match before Mutt performs the test. For example: @@ -6032,11 +6125,13 @@ local $spoolfile. After this point, Mutt runs exactly as if the mail had always been local. + -Note: If you only need to fetch all messages to a +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. + @@ -6088,11 +6183,13 @@ set timeout=15 with relatively good results over my slow modem line. + Note that if you are using mbox as the mail store on UW servers prior to v12.250, the server has been reported to disconnect a client if another client selects the same folder. + The Folder Browser diff --git a/doc/mutt.css b/doc/mutt.css index a6623c18..02582332 100644 --- a/doc/mutt.css +++ b/doc/mutt.css @@ -14,5 +14,8 @@ font-weight:normal; vertical-align:top; } - pre.screen { background:#f0f0f0; border:1px solid #c0c0c0; padding:5px; } + pre.screen, div.note { background:#f0f0f0; border:1px solid #c0c0c0; padding:5px; } + div.note h3 { font-size:small; font-style:italic; font-variant: small-caps; } + div.note h3:after { content: ":" } + div.note { margin-bottom: 5px; } } -- 2.40.0