Changeset 5487:6fd1fa2d98bc

Timestamp:

2008-08-22 08:49:07 (3 months ago)

Author:

Rocco Rutte <pdmef@…>

Branch:

HEAD

Message:

Manual: fix/improve markup/content, see #3109

Files:

• ChangeLog (modified) (1 diff)
• doc/manual.xml.head (modified) (71 diffs)

ChangeLog

@@ +1 @@
+2008-08-21 10:42 +0200  Rocco Rutte  <pdmef@gmx.net>  (15d93fe50e62)
+
+        * init.h: Clarify documentation for $config_charset. Closes #2021.
+
+2008-08-21 10:30 +0200  Rocco Rutte  <pdmef@gmx.net>  (bc8b07e9e95b)
+
+        * ChangeLog, doc/manual.xml.head: Improve color/mono command synopsis.
+        Closes #2630.
+
 2008-08-21 09:36 +0200  Rocco Rutte  <pdmef@gmx.net>  (4139ac196ca8)
 

doc/manual.xml.head

@@ -187 +187 @@
 </thead>
 <tbody>
-<row><entry>j or Down</entry><entry>next-entry</entry><entry>move to the next entry</entry></row>
-<row><entry>k or Up</entry><entry>previous-entry</entry><entry>move to the previous entry</entry></row>
-<row><entry>z or PageDn</entry><entry>page-down</entry><entry>go to the next page</entry></row>
-<row><entry>Z or PageUp</entry><entry>page-up</entry><entry>go to the previous page</entry></row>
-<row><entry>= or Home</entry><entry>first-entry</entry><entry>jump to the first entry</entry></row>
-<row><entry>* or End</entry><entry>last-entry</entry><entry>jump to the last entry</entry></row>
+<row><entry>j or &lt;Down&gt;</entry><entry>next-entry</entry><entry>move to the next entry</entry></row>
+<row><entry>k or &lt;Up&gt;</entry><entry>previous-entry</entry><entry>move to the previous entry</entry></row>
+<row><entry>z or &lt;PageDn&gt;</entry><entry>page-down</entry><entry>go to the next page</entry></row>
+<row><entry>Z or &lt;PageUp&gt;</entry><entry>page-up</entry><entry>go to the previous page</entry></row>
+<row><entry>= or &lt;Home&gt;</entry><entry>first-entry</entry><entry>jump to the first entry</entry></row>
+<row><entry>* or &lt;End&gt;</entry><entry>last-entry</entry><entry>jump to the last entry</entry></row>
 <row><entry>q</entry><entry>quit</entry><entry>exit the current menu</entry></row>
 <row><entry>?</entry><entry>help</entry><entry>list all keybindings for the current menu</entry></row>
@@ -297 +297 @@
 Mutt automatically filters out repeated items from the history.  It
 also mimics the behavior of some shells by ignoring items starting
-with a space.
-</para>
-
-<para>
-The latter feature can be useful in macros to not clobber the history's
-valuable entries with unwanted entries.
+with a space. The latter feature can be useful in macros to not clobber
+the history's valuable entries with unwanted entries.
 </para>
 
@@ -329 +325 @@
 <para>
 Common keys used to navigate through and manage messages in the index
-are shown in <xref linkend="tab-key-index"/>.
-</para>
-
-<para>
-
+are shown in <xref linkend="tab-key-index"/>. How messages are presented
+in the index menu can be customized using the
+<link linkend="index-format">&dollar;index&lowbar;format</link> variable.
+</para>
+
+<para>
 <table id="tab-key-index">
 <title>Most common message index keys</title>
@@ -376 +373 @@
 </para>
 
-<sect3>
-<title>Status Flags</title>
-
 <para>
 In addition to who sent the message and the subject, a short summary of
@@ -384 +378 @@
 Zero or more of the ``flags'' in <xref linkend="tab-msg-status-flags"/>
 may appear, some of which can be turned on or off using these functions:
-</para>
-
-<itemizedlist>
-<listitem>
-
-<para>
-<emphasis role="bold">set-flag</emphasis> (default: w)
-</para>
-</listitem>
-<listitem>
-
-<para>
-<emphasis role="bold">clear-flag</emphasis> (default: W)
-</para>
-</listitem>
-
-</itemizedlist>
+<literal>set-flag</literal> and <literal>clear-flag</literal> bound by default
+to ``w'' and ``W'' respectively.
+</para>
 
 <para>
@@ -446 +426 @@
 </table>
 
-</sect3>
-
 </sect2>
 
@@ -460 +438 @@
 
 <para>
-
 <table id="tab-key-pager">
 <title>Most common pager keys</title>
@@ -482 +459 @@
 </tgroup>
 </table>
-
 </para>
 
@@ -488 +464 @@
 In addition to key bindings in <xref linkend="tab-key-pager"/>,
 many of the functions from the <emphasis>index</emphasis> are available in
-the pager, such as <emphasis>delete-message</emphasis> or <emphasis>copy-message</emphasis> (this is one
-advantage over using an external pager to view messages).
+the pager, such as <literal>delete-message</literal> or <literal>copy-message</literal>
+(this is one advantage over using an external pager to view messages).
 </para>
 
@@ -550 +526 @@
 
 <para>
-Mutt uses these attributes for handling text/enriched messages, and they
-can also be used by an external <link linkend="auto-view">autoview</link>
-script for highlighting purposes.  <emphasis role="bold">Note:</emphasis> If you change the colors for your
+Mutt uses these attributes for handling <literal>text/enriched</literal>
+messages, and they can also be used by an external
+<link linkend="auto-view">autoview</link> script for highlighting purposes.
+<emphasis role="bold">Note:</emphasis> 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.
@@ -625 +602 @@
 
 <para>
-<emphasis role="bold">create-alias</emphasis><anchor id="create-alias"/> (default: a)
-
-</para>
-
+In addition, the <emphasis>index</emphasis> and <emphasis>pager</emphasis>
+have these interesting functions:
+</para>
+
+<variablelist>
+
+<varlistentry>
+<term></term>
+<listitem><para></para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<literal>create-alias</literal><anchor id="create-alias"/> (default: a)
+</term>
+<listitem>
 <para>
 Creates a new alias based upon the current message (or prompts for a
@@ -636 +625 @@
 does not add the aliases specified there-in, you must also <link linkend="source">source</link> the file.
 </para>
-
-<para>
-<emphasis role="bold">check-traditional-pgp</emphasis><anchor id="check-traditional-pgp"/> (default: ESC P)
-
-</para>
-
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<literal>check-traditional-pgp</literal><anchor id="check-traditional-pgp"/> (default: ESC P)
+</term>
+<listitem>
 <para>
 This function will search the current message for content signed or
@@ -650 +641 @@
 effect.
 </para>
-
-<para>
-<emphasis role="bold">display-toggle-weed</emphasis><anchor id="display-toggle-weed"/> (default: h)
-
-</para>
-
-<para>
-Toggles the weeding of message header fields specified by <link linkend="ignore">ignore</link> commands.
-</para>
-
-<para>
-<emphasis role="bold">edit</emphasis><anchor id="edit"/> (default: e)
-
-</para>
-
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<literal>edit</literal><anchor id="edit"/> (default: e)
+</term>
+<listitem>
 <para>
 This command (available in the ``index'' and ``pager'') allows you to
@@ -672 +656 @@
 marked for deletion.
 </para>
-
-<para>
-<emphasis role="bold">edit-type</emphasis><anchor id="edit-type"/>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<literal>edit-type</literal><anchor id="edit-type"/>
 
 (default: &circ;E on the attachment menu, and in the pager and index menus; &circ;T on the
 compose menu)
-</para>
-
+</term>
+<listitem>
 <para>
 This command is used to temporarily edit an attachment's content
@@ -695 +682 @@
 to send.
 </para>
-
-<para>
-<emphasis role="bold">enter-command</emphasis><anchor id="enter-command"/> (default: ``:'')
-
-</para>
-
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<literal>enter-command</literal><anchor id="enter-command"/> (default: ``:'')
+</term>
+<listitem>
 <para>
 This command is used to execute any command you would normally put in a
@@ -707 +696 @@
 fly.
 </para>
-
-<para>
-<emphasis role="bold">extract-keys</emphasis><anchor id="extract-keys"/> (default: &circ;K)
-
-</para>
-
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<literal>extract-keys</literal><anchor id="extract-keys"/> (default: &circ;K)
+</term>
+<listitem>
 <para>
 This command extracts PGP public keys from the current or tagged
 message(s) and adds them to your PGP public key ring.
 </para>
-
-<para>
-<emphasis role="bold">forget-passphrase</emphasis><anchor id="forget-passphrase"/> (default:
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<literal>forget-passphrase</literal><anchor id="forget-passphrase"/> (default:
 &circ;F)
- 
-</para>
-
+</term>
+<listitem>
 <para>
 This command wipes the passphrase(s) from memory. It is useful, if
 you misspelled the passphrase.
 </para>
-
-<para>
-<emphasis role="bold">list-reply</emphasis><anchor id="list-reply"/> (default: L)
-
-</para>
-
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<literal>list-reply</literal><anchor id="list-reply"/> (default: L)
+</term>
+<listitem>
 <para>
 Reply to the current or tagged message(s) by extracting any addresses which
@@ -743 +738 @@
 the message you are replying to.
 </para>
-
-<para>
-<emphasis role="bold">pipe-message</emphasis><anchor id="pipe-message"/> (default: &verbar;)
-
-</para>
-
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<literal>pipe-message</literal><anchor id="pipe-message"/> (default: &verbar;)
+</term>
+<listitem>
 <para>
 Asks for an external Unix command and pipes the current or
@@ -754 +751 @@
 <link linkend="pipe-sep">&dollar;pipe&lowbar;sep</link> and <link linkend="wait-key">&dollar;wait&lowbar;key</link> control the exact behavior of this function.
 </para>
-
-<para>
-<emphasis role="bold">resend-message</emphasis><anchor id="resend-message"/> (default: ESC e)
-
-</para>
-
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<literal>resend-message</literal><anchor id="resend-message"/> (default: ESC e)
+</term>
+<listitem>
 <para>
 With resend-message, mutt takes the current message as a template for a
@@ -774 +773 @@
 as a message/rfc822 body part.
 </para>
-
-<para>
-<emphasis role="bold">shell-escape</emphasis><anchor id="shell-escape"/> (default: !)
-
-</para>
-
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<literal>shell-escape</literal><anchor id="shell-escape"/> (default: !)
+</term>
+<listitem>
 <para>
 Asks for an external Unix command and executes it.  The <link linkend="wait-key">&dollar;wait&lowbar;key</link> can be used to control
@@ -786 +787 @@
 the return status of the named command.
 </para>
-
-<para>
-<emphasis role="bold">toggle-quoted</emphasis><anchor id="toggle-quoted"/> (default: T)
-
-</para>
-
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<literal>toggle-quoted</literal><anchor id="toggle-quoted"/> (default: T)
+</term>
+<listitem>
 <para>
 The <emphasis>pager</emphasis> uses the <link linkend="quote-regexp">&dollar;quote&lowbar;regexp</link> variable to detect quoted text when
@@ -799 +802 @@
 quoted text in the way.
 </para>
-
-<para>
-<emphasis role="bold">skip-quoted</emphasis><anchor id="skip-quoted"/> (default: S)
-
-</para>
-
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<literal>skip-quoted</literal><anchor id="skip-quoted"/> (default: S)
+</term>
+<listitem>
 <para>
 This function will go to the next line of non-quoted text which come
 after a line of quoted text in the internal pager.
 </para>
+</listitem>
+</varlistentry>
+
+</variablelist>
 
 </sect2>
@@ -817 +826 @@
 <title>Sending Mail</title>
 
+<sect2>
+<title>Introduction</title>
+
 <para>
 The bindings shown in <xref linkend="tab-key-send"/> are available in the
-<emphasis>index</emphasis> for sending messages.
+<emphasis>index</emphasis> and <emphasis>pager</emphasis> to start a new message.
 </para>
 
@@ -845 +857 @@
 
 <para>
-Bouncing a message sends the message as is to the recipient you
-specify.  Forwarding a message allows you to add comments or
+<emphasis>Bouncing</emphasis> a message sends the message as is to the recipient you
+specify.  <emphasis>Forwarding</emphasis> a message allows you to add comments or
 modify the message you are forwarding.  These items are discussed
 in greater detail in the next chapter ``<link linkend="forwarding-mail">Forwarding
@@ -867 +879 @@
 
 <para>
-Mutt will then automatically start your <link linkend="editor">&dollar;editor</link> on the message body.  If the <link linkend="edit-headers">&dollar;edit&lowbar;headers</link> variable is set, the headers will be at
-the top of the message in your editor.  Any messages you are replying
-to will be added in sort order to the message, with appropriate <link linkend="attribution">&dollar;attribution</link>, <link linkend="indent-string">&dollar;indent&lowbar;string</link> and <link linkend="post-indent-string">&dollar;post&lowbar;indent&lowbar;string</link>.  When forwarding a
-message, if the <link linkend="mime-forward">&dollar;mime&lowbar;forward</link>
+Mutt will then automatically start your <link linkend="editor">&dollar;editor</link>
+on the message body. If the <link linkend="edit-headers">&dollar;edit&lowbar;headers</link>
+variable is set, the headers will be at the top of the message in your editor.
+Any messages you are replying to will be added in sort order to the message,
+with appropriate <link linkend="attribution">&dollar;attribution</link>,
+<link linkend="indent-string">&dollar;indent&lowbar;string</link> and
+<link linkend="post-indent-string">&dollar;post&lowbar;indent&lowbar;string</link>.
+When forwarding a message, if the <link linkend="mime-forward">&dollar;mime&lowbar;forward</link>
 variable is unset, a copy of the forwarded message will be included.  If
 you have specified a <link linkend="signature">&dollar;signature</link>, it
@@ -879 +895 @@
 Once you have finished editing the body of your mail message, you are
 returned to the <emphasis>compose</emphasis> menu providing the functions
-show in <xref linkend="tab-func-compose"/>.
+show in <xref linkend="tab-func-compose"/> to modify, send or postpone the
+message.
 </para>
 
@@ -918 +935 @@
 
 <para>
-<emphasis role="bold">Note:</emphasis> The attach-message function will prompt you for a folder to
+The compose menu is also used to edit the attachments for a message which can be eiter files
+or other messages. The <literal>attach-message</literal> 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
 operations like composing a new mail, replying, forwarding, etc. are
-not permitted when you are in that folder. The &percnt;r in <link linkend="status-format">&dollar;status&lowbar;format</link> will change to
+not permitted when you are in that folder. The &percnt;r in
+<link linkend="status-format">&dollar;status&lowbar;format</link> will change to
 a 'A' to indicate that you are in attach-message mode.
 </para>
+
+</sect2>
 
 <sect2>
@@ -930 +951 @@
 
 <para>
-When editing the header of your outgoing message, there are a couple of
-special features available.
-</para>
+When editing the header because of <link linkend="edit-headers">&dollar;edit&lowbar;headers</link>
+being set, there are a couple of special features available.
+</para>
+
+<sect3>
+<title>Fcc: pseudo header</title>
 
 <para>
@@ -939 +963 @@
 <literal>Fcc:</literal> <emphasis>filename</emphasis>
 
-Mutt will pick up <emphasis>filename</emphasis>
+as a header, Mutt will pick up <emphasis>filename</emphasis>
 just as if you had used the <emphasis>edit-fcc</emphasis> function in the <emphasis>compose</emphasis> menu.
-</para>
+This header will not be included in sent messages.
+</para>
+
+</sect3>
+
+<sect3>
+<title>Attach: pseudo header</title>
 
 <para>
@@ -949 +979 @@
 
 where <emphasis>filename</emphasis> is the file to attach and <emphasis>description</emphasis> is an
-optional string to use as the description of the attached file.
-</para>
-
-<para>
-When replying to messages, if you remove the <emphasis>In-Reply-To:</emphasis> field from
-the header field, Mutt will not generate a <emphasis>References:</emphasis> field, which
-allows you to create a new message thread.
-</para>
-
-<para>
-Also see <link linkend="edit-headers">&dollar;edit&lowbar;headers</link>.
-</para>
-
-</sect2>
-
-<sect2>
-<title>Using Mutt with PGP</title>
+optional string to use as the description of the attached file. This header, too, won't be send
+out.
+</para>
+
+</sect3>
+
+<sect3>
+<title>Pgp: pseudo header</title>
 
 <para>
@@ -1056 +1077 @@
 </para>
 
+</sect3>
+
+<sect3>
+<title>In-Reply-To: header</title>
+
+<para>
+When replying to messages, the <emphasis>In-Reply-To:</emphasis> header contains the
+Message-Id of the message(s) you reply to. If you remove its value, Mutt will not generate a
+<emphasis>References:</emphasis> field, which allows you to create a new message thread, for example
+to create a new list to a mailing list without having to needing to enter the mailing list's address.
+</para>
+
+</sect3>
+
 </sect2>
 
 <sect2>
-<title>Sending anonymous messages via mixmaster.</title>
-
-<para>
-You may also have configured mutt to co-operate with Mixmaster, an
+<title>Sending anonymous messages via mixmaster</title>
+
+<para>
+You may also have compiled mutt to co-operate with Mixmaster, an
 anonymous remailer.  Mixmaster permits you to send your messages
 anonymously using a chain of remailers. Mixmaster support in mutt is for 
@@ -1206 +1241 @@
 <para>
 Bouncing and forwarding let you send an existing message to recipients
-that you specify.  Bouncing a message uses the <link linkend="sendmail">&dollar;sendmail</link> command to send a copy to alternative addresses as if
-they were the message's original recipients.  Forwarding a message, on
-the other hand, allows you to modify the message before it is resent
-(for example, by adding your own comments). The default key bindings
-are shown in <xref linkend="tab-key-fwd"/>.
-</para>
-
-<para>
-
-<table id="tab-key-fwd">
-<title>Message forwarding/bouncing keys</title>
-<tgroup cols="3">
-<thead>
-<row><entry>Key</entry><entry>Function</entry><entry>Description</entry></row>
-</thead>
-<tbody>
-<row><entry>f</entry><entry>forward</entry><entry>forward message</entry></row>
-<row><entry>b</entry><entry>bounce</entry><entry>bounce (remail) message</entry></row>
-</tbody>
-</tgroup>
-</table>
-
+that you specify. Bouncing a message sends a verbatim copy of a message
+to alternative addresses as if they were the message's original recipients.
+Forwarding a message, on the other hand, allows you to modify the message
+before it is resent (for example, by adding your own comments). Bouncing
+is done using the <literal>bounce</literal> function and forwarding
+using the <literal>forward</literal> command bound to ``b'' and ``f''
+respectively.
 </para>
 
@@ -1257 +1277 @@
 <para>
 At times it is desirable to delay sending a message that you have
-already begun to compose.  When the <emphasis>postpone-message</emphasis> function is
+already begun to compose.  When the <literal>postpone-message</literal> function is
 used in the <emphasis>compose</emphasis> menu, the body of your message and attachments
 are stored in the mailbox specified by the <link linkend="postponed">&dollar;postponed</link> variable.  This means that you can recall the
@@ -1289 +1309 @@
 <chapter id="configuration">
 <title>Configuration</title>
+
+<sect1>
+<title>Location of initialization files</title>
 
 <para>
@@ -1320 +1343 @@
 </para>
 
+</sect1>
+
 <sect1 id="muttrc-syntax" xreflabel="Syntax of Initialization Files">
 <title>Syntax of Initialization Files</title>
@@ -1422 +1447 @@
 </para>
 
+<para>
+All configuration files are expected to be in the current locale as
+specified by the <link linkend="charset">&dollar;charset</link> variable
+which doesn't have a default value since it's determined by Mutt at startup.
+If a configuration file is not encoded in the same character set the
+<link linkend="config-charset">&dollar;config&lowbar;charset</link>
+variable should be used: all lines starting with the next are recoded
+from &dollar;config&lowbar;charset to &dollar;charset.
+</para>
+
+<para>
+This mechanism should be avoided if possible as it has the
+following implications:
+</para>
+
+<para>
+<itemizedlist>
+
+<listitem><para>These variables should be set early in a configuration
+file with &dollar;charset preceeding &dollar;config&lowbar;charset so Mutt
+know what character set to convert to.</para></listitem>
+
+<listitem><para>If &dollar;config&lowbar;charset is set, it should be set
+in each configuration file because the value is global and <emphasis>not</emphasis>
+per configuration file.</para></listitem>
+
+<listitem><para>Because Mutt first recodes a line before it attempts to parse it,
+a conversion introducing question marks or other characters as
+part of errors (unconvertable characters, transliteration) may introduce syntax
+errors or silently change the meaning of certain tokens (e.g. inserting
+question marks into regular expressions).</para></listitem>
+
+</itemizedlist>
+</para>
+
 </sect1>
 
@@ -1557 +1617 @@
 <para>
 In the alias menu, you can select as many aliases as you want with the
-<emphasis>select-entry</emphasis> key (default: RET), and use the <emphasis>exit</emphasis> key
-(default: q) to return to the address prompt.
+<literal>select-entry</literal> key (default: &lt;Return&gt;), and use the
+<emphasis>exit</emphasis> key (default: q) to return to the address prompt.
 </para>
 
@@ -1805 +1865 @@
 However, the sorting method is not restored to its previous value when
 reading a different mailbox.  To specify a <emphasis>default</emphasis> command, use the
-pattern ``.'':
-</para>
-
-<para>
-
+pattern ``.'' before other folder-hooks adjusting a value on a per-folder basis
+because folder-hooks are evaluated in the order given in the configuration file.
+The following example will set the <link linkend="sort">sort</link> variable
+to <literal>date-sent</literal> for all folders but to <literal>threads</literal>
+for all folders containing ``mutt'' in their name.
+</para>
+
+<para>
 <screen>