X-Git-Url: http://git.madism.org/?a=blobdiff_plain;f=doc%2Fmanual.sgml.head;h=11736666dd610488141161211d4d7b1aad69413d;hb=69bd7df1ce9e5c6a64b5128f85c1f91912d2f510;hp=6469349d26d04fe34ffb053880f71643def5f8cc;hpb=c6b020e0fa5c38e4fd8a6ffb75e00338c0535b11;p=apps%2Fmadmutt.git

diff --git a/doc/manual.sgml.head b/doc/manual.sgml.head
index 6469349..1173666 100644
--- a/doc/manual.sgml.head
+++ b/doc/manual.sgml.head
@@ -1162,7 +1162,7 @@ usually place your <ref id="commands" name="commands"> to configure Mutt-ng.
 
 <!--}}}--> 
 
-<sect>Syntax of Initialization Files<label id="muttrc-syntax"> <!--{{{--> 
+<sect>Basic Syntax of Initialization Files<label id="muttrc-syntax"> <!--{{{--> 
 <p>
 
 An initialization file consists of a series of <ref id="commands"
@@ -1235,27 +1235,199 @@ line1 ``continues'' until line4. however, the part after the &num; is a
 comment which includes line3 and line4. line5 is a new line of its own and
 thus is interpreted again.
 
-It is also possible to substitute the output of a Unix command in an
-initialization file.  This is accomplished by enclosing the command in
-backquotes (``).  For example,
+The commands understood by mutt are explained in the next paragraphs.
+For a complete list, see the <ref id="commands" name="command reference">.
+
+<!--}}}--> 
+
+<sect>Expansion within variables <!--{{{--> 
+
+  <p>Besides just assign static content to variables, there's plenty of
+  ways of adding external and more or less dynamic content.
+
+  <sect1>Commands' Output 
+
+    <p>It is possible to substitute the output of a Unix command in an
+    initialization file.  This is accomplished by enclosing the command
+    in backquotes (``) as in, for example:
+
 <tscreen><verb>
 my_hdr X-Operating-System: `uname -a`
 </verb></tscreen>
-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
-the first line of output from the Unix command will be substituted.
 
-UNIX environments can be accessed like the way it is done in shells like
-sh and bash: Prepend the name of the environment by a ``&dollar;''.  For
-example,
+    <p>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 the first line of output from the Unix command
+    will be substituted.
+
+  <sect1>Environment Variables 
+
+    <p>UNIX environments can be accessed like the way it is done in
+    shells like sh and bash: Prepend the name of the environment by a
+    ``&dollar;'' sign. For example,
+
 <tscreen><verb>
 set record=+sent_on_$HOSTNAME
 </verb></tscreen>
 
-The commands understood by mutt are explained in the next paragraphs.
-For a complete list, see the <ref id="commands" name="command reference">.
+    <p>sets the <ref id="record" name="&dollar;record"> variable to the
+    string <em/+sent_on_/ and appends the value of the evironment
+    variable <tt>&dollar;HOSTNAME</tt>.
 
-<!--}}}--> 
+    <p><bf/Note:/ There will be no warning if an environment variable
+    is not defined. The result will of the expansion will then be empty.
+
+  <sect1>Configuration Variables 
+
+    <p>As for environment variables, the values of all configuration
+    variables as string can be used in the same way, too. For example,
+
+<tscreen><verb>
+set imap_home_namespace = $folder
+</verb></tscreen>
+
+    <p>would set the value of <ref id="imap_home_namespace"
+    name="&dollar;imap&lowbar;home&lowbar;namespace"> to the value to
+    which <ref id="folder" name="&dollar;folder"> is <em/currently/ set
+    to.
+
+    <p><bf/Note:/ There're no logical links established in such cases so
+    that the the value for <ref id="imap_home_namespace"
+    name="&dollar;imap&lowbar;home&lowbar;namespace"> won't change even
+    if <ref id="folder" name="&dollar;folder"> gets changed.
+
+    <p><bf/Note:/ There will be no warning if a configuration variable
+    is not defined or is empty. The result will of the expansion will
+    then be empty.
+
+  <sect1>Self-Defined Variables 
+
+    <p>Mutt-ng flexibly allows users to define their own variables. To
+    avoid conflicts with the standard set and to prevent misleading
+    error messages, there's a reserved namespace for them: all
+    user-defined variables must be prefixed with <tt/user_/ and can be
+    used just like any ordinary configuration or environment
+    variable.
+
+    <p>For example, to view the manual, users can either define two
+    macros like the following
+
+<tscreen><verb>
+macro generic &lt;F1&gt; "!less -r /path/to/manual" "Show manual"
+macro pager &lt;F1&gt; "!less -r /path/to/manual" "Show manual"
+</verb></tscreen>
+
+    <p>for <tt/generic/, <tt/pager/ and <tt/index/. The alternative is to
+    define a custom variable like so:
+
+<tscreen><verb>
+set user_manualcmd = "!less -r /path/to_manual"
+macro generic &lt;F1&gt; "$user_manualcmd&lt;enter&gt;" "Show manual"
+macro pager &lt;F1&gt; "$user_manualcmd&lt;enter&gt;" "Show manual"
+macro index &lt;F1&gt; "$user_manualcmd&lt;enter&gt;" "Show manual"
+</verb></tscreen>
+
+    <p>to re-use the command sequence as in:
+
+<tscreen><verb>
+macro index &lt;F2&gt; "$user_manualcmd | grep '\^[ ]\\+~. '" "Show Patterns"
+</verb></tscreen>
+
+    <p>Using this feature, arbitrary sequences can be defined once and
+    recalled and reused where necessary. More advanced scenarios could
+    include to save a variable's value at the beginning of macro
+    sequence and restore it at end.
+
+    <p>When the variable is first defined, the first value it gets
+    assigned is also the initial value to which it can be reset using
+    the <tt/reset/ command.
+
+    <p>The complete removal is done via the <tt/unset/ keyword.
+
+    <p>After the following sequence:
+
+<tscreen><verb>
+set user_foo = 42
+set user_foo = 666
+</verb></tscreen>
+
+    <p>the variable <tt>$user_foo</tt> has a current value of 666 and an
+    initial of 42. The query
+
+<tscreen><verb>
+set ?user_foo
+</verb></tscreen>
+
+    <p>will show 666. After doing the reset via
+
+<tscreen><verb>
+reset user_foo
+</verb></tscreen>
+
+    <p>a following query will give 42 as the result. After unsetting it
+    via
+
+<tscreen><verb>
+unset user_foo
+</verb></tscreen>
+
+    <p>any query or operation (except the noted expansion within other
+    statements) will lead to an error message.
+
+  <sect1>Pre-Defined Variables 
+
+    <p>In order to allow users to share one setup over a number of
+    different machines without having to change its contents, there's a
+    number of pre-defined variables. These are prefixed with
+    <tt/muttng_/ and are read-only, i.e. they cannot be set, unset or
+    reset. The reference chapter lists all available variables.
+
+    <p><em> Please consult the local copy of your manual for their
+    values as they may differ from different manual sources.</em> Where
+    the manual is installed in can be queried (already using such a
+    variable) by running:
+
+<tscreen><verb>
+muttng -Q muttng_docdir
+</verb></tscreen>
+
+    <p>To extend the example for viewing the manual via self-defined
+    variables, it can be made more readable and more portable by
+    changing the real path in:
+
+<tscreen><verb>
+set user_manualcmd = '!less -r /path/to_manual'
+</verb></tscreen>
+
+    <p>to:
+
+<tscreen><verb>
+set user_manualcmd = "!less -r $muttng_docdir/manual.txt"
+</verb></tscreen>
+
+    <p>which works everywhere if a manual is installed.
+
+    <p><em>Note: this is a draft feature and maybe subject to change in
+    the near future.</em>
+
+  <sect1>Type Conversions 
+
+    <p>A note about variable's types during conversion: internally
+    values are stored in internal types but for any dump/query or set
+    operation they're converted to and from string. That means that
+    there's no need to worry about types when referencing any variable.
+    As an example, the following can be used without harm (besides
+    makeing muttng very likely behave strange):
+
+<tscreen><verb>
+set read_inc = 100
+set folder = $read_inc
+set read_inc = $folder
+set user_magic_number = 42
+set folder = $user_magic_number
+</verb></tscreen>
+
+<!--}}}-->
 
 <sect>Defining/Using aliases<label id="alias"> <!--{{{--> 
 <p>
@@ -1664,82 +1836,132 @@ is ``*'', <em/all entries/ on <tt/alternates/ will be removed.
 
 <sect>Format = Flowed <!--{{{--> 
 
-<p>Mutt-ng contains support for so-called <tt/format=flowed/ messages.
-In the beginning of email, each message had a fixed line width, and
-it was enough for displaying them on fixed-size terminals. But times
-changed, and nowadays hardly anybody still uses fixed-size terminals:
-more people nowaydays use graphical user interfaces, with dynamically
-resizable windows. This led to the demand of a new email format that
-makes it possible for the email client to make the email look nice
-in a resizable window without breaking quoting levels and creating
-an incompatible email format that can also be displayed nicely on
-old fixed-size terminals.
-
-<p>For introductory information on <tt/format=flowed/ messages, see
-<htmlurl url="http://www.joeclark.org/ffaq.html"
-name="&lt;http://www.joeclark.org/ffaq.html&gt;">.
-
-<p>When you receive emails that are marked as <tt/format=flowed/
-messages, and is formatted correctly, mutt-ng will try to reformat
-the message to optimally fit on your terminal. If you want a fixed
-margin on the right side of your terminal, you can set the
-following:
+  <sect1>Introduction <!--{{{--> 
 
-<verb>
-set wrapmargin = 10
-</verb>
+    <p>Mutt-ng contains support for so-called <tt/format=flowed/ messages.
+    In the beginning of email, each message had a fixed line width, and
+    it was enough for displaying them on fixed-size terminals. But times
+    changed, and nowadays hardly anybody still uses fixed-size terminals:
+    more people nowaydays use graphical user interfaces, with dynamically
+    resizable windows. This led to the demand of a new email format that
+    makes it possible for the email client to make the email look nice
+    in a resizable window without breaking quoting levels and creating
+    an incompatible email format that can also be displayed nicely on
+    old fixed-size terminals.
 
-<p>The code above makes the line break 10 columns before the right
-side of the terminal.
+    <p>For introductory information on <tt/format=flowed/ messages, see
+    <htmlurl url="http://www.joeclark.org/ffaq.html"
+    name="&lt;http://www.joeclark.org/ffaq.html&gt;">.
 
-<p>If your terminal is so wide that the lines are embarrassingly long,
-you can also set a maximum line length:
+  <!--}}}-->
 
-<verb>
-set max_line_length = 120
-</verb>
+  <sect1>Receiving: Display Setup <!--{{{--> 
 
-<p>The example above will give you lines not longer than 120
-characters.
+    <p>When you receive emails that are marked as <tt/format=flowed/
+    messages, and is formatted correctly, mutt-ng will try to reformat
+    the message to optimally fit on your terminal. If you want a fixed
+    margin on the right side of your terminal, you can set the
+    following:
 
-<p>When you view at <tt/format=flowed/ messages, you will often see
-the quoting hierarchy like in the following example:
+    <verb>
+    set wrapmargin = 10
+    </verb>
 
-<verb>
-&gt;Bill, can you please send last month's progress report to Mr. 
-&gt;Morgan? We also urgently need the cost estimation for the new 
-&gt;production server that we want to set up before our customer's 
-&gt;project will go live.
-</verb>
+    <p>The code above makes the line break 10 columns before the right
+    side of the terminal.
 
-<p>This obviously doesn't look very nice, and it makes it very
-hard to differentiate between text and quoting character. The
-solution is to configure mutt-ng to "stuff" the quoting:
+    <p>If your terminal is so wide that the lines are embarrassingly long,
+    you can also set a maximum line length:
 
-<verb>
-set stuff_quoted
-</verb>
+    <verb>
+    set max_line_length = 120
+    </verb>
 
-<p>This will lead to a nicer result that is easier to read:
+    <p>The example above will give you lines not longer than 120
+    characters.
 
-<verb>
-&gt; Bill, can you please send last month's progress report to Mr. 
-&gt; Morgan? We also urgently need the cost estimation for the new 
-&gt; production server that we want to set up before our customer's 
-&gt; project will go live.
-</verb>
+    <p>When you view at <tt/format=flowed/ messages, you will often see
+    the quoting hierarchy like in the following example:
 
-<p>If you want mutt-ng to send emails with <tt/format=flowed/ set, you
-need to explicitly set it:
+    <verb>
+    &gt;Bill, can you please send last month's progress report to Mr. 
+    &gt;Morgan? We also urgently need the cost estimation for the new 
+    &gt;production server that we want to set up before our customer's 
+    &gt;project will go live.
+    </verb>
 
-<verb>
-set text_flowed
-</verb>
+    <p>This obviously doesn't look very nice, and it makes it very
+    hard to differentiate between text and quoting character. The
+    solution is to configure mutt-ng to "stuff" the quoting:
 
-<p>Additionally, you have to use an editor which supports writing
-<tt/format=flowed/-conforming emails. For vim, this is done by
-adding <tt/w/ to the formatoptions (see <tt/:h formatoptions/ and
-<tt/:h fo-table/) when writing emails.
+    <verb>
+    set stuff_quoted
+    </verb>
+
+    <p>This will lead to a nicer result that is easier to read:
+
+    <verb>
+    &gt; Bill, can you please send last month's progress report to Mr. 
+    &gt; Morgan? We also urgently need the cost estimation for the new 
+    &gt; production server that we want to set up before our customer's 
+    &gt; project will go live.
+    </verb>
+
+  <!--}}}-->
+
+  <sect1>Sending <!--{{{--> 
+
+    <p>If you want mutt-ng to send emails with <tt/format=flowed/ set, you
+    need to explicitly set it:
+
+    <verb>
+    set text_flowed
+    </verb>
+
+    <p>Additionally, you have to use an editor which supports writing
+    <tt/format=flowed/-conforming emails. For vim, this is done by
+    adding <tt/w/ to the formatoptions (see <tt/:h formatoptions/ and
+    <tt/:h fo-table/) when writing emails.
+
+    <p>Also note that <em/format=flowed/ knows about ``space-stuffing'',
+    that is, when sending messages, some kinds of lines have to be
+    indented with a single space on the sending side. On the receiving
+    side, the first space (if any) is removed. As a consequence and in
+    addition to the above simple setting, please keep this in mind when
+    making manual formattings within the editor. Also note that mutt-ng
+    currently violates the standard (RfC 3676) as it does not
+    space-stuff lines starting with:
+
+    <itemize>
+
+      <item><tt/&gt;/ This is <em/not/ the quote character but a right
+        angle used for other reasons
+
+      <item><tt/From/ with a trailing space.
+
+      <item>just a space for formatting reasons
+
+    </itemize>
+
+    Please make sure that you manually prepend a space to each of them.
+
+  <!--}}}-->
+
+  <sect1>Additional Notes <!--{{{-->
+
+    <p> For completeness, the <ref id="delete_space"
+    name="&dollar;delete&lowbar;space"> variable provides the mechanism
+    to generate a <tt/DelSp=yes/ parameter on <em/outgoing/ messages.
+    According to the standard, clients receiving a <tt/format=flowed/
+    messages should delete the last space of a flowed line but still
+    interpret the line as flowed. Because flowed lines usually contain
+    only one space at the end, this parameter would make the receiving
+    client concatenate the last word of the previous with the first of
+    the current line <em/without/ a space. This makes ordinary text
+    unreadable and is intended for languages rarely using spaces. So
+    please use this setting only if you're sure what you're doing.
+
+  <!--}}}-->
 
 <!--}}}--> 
 
@@ -2131,8 +2353,8 @@ message will ever get marked as read or deleted.
 and the <tt>&tilde;n</tt> pattern:
 
 <verb>
-color   black   yellow  "~n 10-"
-color   red     yellow  "~n 100-"</verb>
+color index  black   yellow  "~n 10-"
+color index  red     yellow  "~n 100-"</verb>
 
 <p>The rules above mark all messages with a score between 10 and 99
 with black and yellow, and messages with a score greater or equal
@@ -4298,6 +4520,164 @@ muttrc.
 
 <!--}}}--> 
 
+<chapt>Security Considerations <!--{{{--> 
+
+  <p>First of all, mutt-ng contains no security holes included by
+  intention but may contain unknown security holes. As a consequence,
+  please run mutt-ng only with as few permissions as possible.
+
+  <p>Please do not run mutt-ng as the super user.
+
+  <p>When configuring mutt-ng, there're some points to note about secure
+  setups.
+
+  <p>In practice, mutt-ng can be easily made as vulnerable as even the
+  most insecure mail user agents (in their default configuration) just
+  by changing mutt-ng's configuration files: it then can execute
+  arbitrary programs and scripts attached to messages, send out private
+  data on its own, etc. Although this is not believed to the common type
+  of setup, please read this chapter carefully.
+
+  <sect>Passwords <!--{{{--> 
+
+    <p>Although mutt-ng can be told the various passwords for accounts,
+    please never store passwords in configuration files. Besides the
+    fact that the system's operator can always read them, you could
+    forget to replace the actual password with asterisks when reporting
+    a bug or asking for help via, for example, a mailing list so that
+    your mail including your password could be archived by internet
+    search engines, etc. Please never store passwords on disk.
+
+  <!--}}}-->
+
+  <sect>Temporary Files <!--{{{--> 
+
+    <p>Mutt-ng uses many temporary files for viewing messages, verifying
+    digital signatures, etc. The <ref id="umask" name="&dollar;umask">
+    variable can be used to change the default permissions of these
+    files. Please only change it if you really know what you are doing.
+    Also, a different location for these files may be desired which can
+    be changed via the <ref id="tmpdir" name="&dollar;tmpdir"> variable.
+
+  <!--}}}-->
+
+  <sect>Information Leaks <!--{{{--> 
+
+  <sect1>Message-ID: headers <!--{{{--> 
+
+    <p>In the default configuration, mutt-ng will leak some information
+    to the outside world when sending messages: the generation of
+    <tt/Message-ID:/ headers includes a step counter which is increased
+    (and rotated) with every message sent. If you'd like to hide this
+    information probably telling others how many mail you sent in which
+    time, you at least need to remove the <tt/%P/ expando from the
+    default setting of the <ref id="msgid_format"
+    name="&dollar;msgid&lowbar;format"> variable. Please make sure that
+    you really know how local parts of these <tt/Message-ID:/ headers
+    are composed.
+
+  <!--}}}-->
+
+  <sect1>mailto:-style links <!--{{{--> 
+
+    <p>As mutt-ng be can be set up to be the mail client to handle
+    <tt/mailto:/ style links in websites, there're security
+    considerations, too. To keep the old behavior by default, mutt-ng
+    will be strict in interpreting them which means that arbitrary
+    header fields can be embedded in these links which could override
+    existing header fields or attach arbitrary files. This may be
+    problematic if the <ref id="edit_headers"
+    name="&dollar;edit&lowbar;headers"> variable is <em/unset/, i.e. the
+    user doesn't want to see header fields while editing the message.
+
+    <p>For example, following a link like
+
+    <verb>
+mailto:joe@host?Attach=~/.gnupg/secring.gpg</verb>
+
+    will send out the user's private gnupg keyring to <tt/joe@host/ if
+    the user doesn't follow the information on screen carefully
+    enough.
+
+    <p>When <em/unsetting/ the <ref id="strict_mailto"
+    name="&dollar;strict&lowbar;mailto"> variable, mutt-ng will
+
+    <itemize>
+
+      <item>be less strict when interpreting these links by
+        prepending a <tt/X-Mailto-/ string to all header fields
+        embedded in such a link <em/and/
+
+      <item>turn on the <ref id="edit_headers"
+        name="&dollar;edit&lowbar;headers"> variable by
+        force to let the user see all the headers
+        (because they still may leak information.)
+
+    </itemize>
+
+  <!--}}}-->
+
+  <!--}}}-->
+
+  <sect>External applications <!--{{{--> 
+
+    <p>Mutt-ng in many places has to rely on external applications or
+    for convenience supports mechanisms involving external
+    applications.
+
+    <sect1>mailcap <!--{{{--> 
+
+      <p>One of these is the <tt/mailcap/ mechanism as defined by RfC
+      1524. Mutt-ng can be set up to <em/automatically/ execute any
+      given utility as listed in one of the mailcap files (see the
+      <ref id="mailcap_path" name="&dollar;mailcap&lowbar;path">
+      variable for details.) 
+
+      These utilities may have a variety of security vulnerabilities,
+      including overwriting of arbitrary files, information leaks or
+      other exploitable bugs.  These vulnerabilities may go unnoticed by
+      the user, especially when they are called automatically (and
+      without interactive prompting) from the mailcap file(s). When
+      using mutt-ng's autoview mechanism in combination with mailcap
+      files, please be sure to...
+
+      <itemize>
+
+        <item>manually select trustworth applications with a reasonable
+        calling sequence
+
+        <item>periodically check the contents of mailcap files,
+        especially after software installations or upgrades
+
+        <item>keep the software packages referenced in the mailcap file up to date
+
+        <item>leave the <ref id="mailcap_sanitize"
+        name="&dollar;mailcap&lowbar;sanitize"> variable in its default
+        state to restrict mailcap expandos to a safe set of characters
+
+      </itemize>
+
+    <!--}}}-->
+
+    <sect1>Other <!--{{{--> 
+
+      <p>Besides the mailcap mechanism, mutt-ng uses a number of other
+      external utilities for operation.
+
+      <p>The same security considerations apply for these as for tools
+      involved via mailcap (for example, mutt-ng is vulnerable to Denial
+      of Service Attacks with compressed folders support if the
+      uncompressed mailbox is too large for the disk it is saved to.)
+
+      <p>As already noted, most of these problems are not built in but
+      caused by wrong configuration, so please check your configuration.
+
+    <!--}}}-->
+
+  <!--}}}-->
+
+<!--}}}-->
+
 <chapt>Reference <!--{{{--> 
 
 <sect>Command line options<label id="commandline"> <!--{{{--> 
@@ -4307,11 +4687,10 @@ mailbox.  However, it is possible to read other mailboxes and
 to send messages from the command line as well.
 
 <tscreen><verb>
--A	expand an alias
+-A      expand an alias
 -a      attach a file to a message
 -b      specify a blind carbon-copy (BCC) address
 -c      specify a carbon-copy (Cc) address
--D      print the value of all variables on stdout
 -e      specify a config command to be run after initialization files are read
 -f      specify a mailbox to load
 -F      specify an alternate file to read initialization commands
@@ -4324,6 +4703,8 @@ to send messages from the command line as well.
 -Q      query a configuration variable
 -R      open mailbox in read-only mode
 -s      specify a subject (enclose in quotes if it contains spaces)
+-t      dump the value of all variables to stdout
+-T      dump the value of all changed variables to stdout
 -v      show version number and compile-time definitions
 -x      simulate the mailx(1) compose mode
 -y      show a menu containing the files specified by the mailboxes command
@@ -4375,6 +4756,7 @@ of the file ``&tilde;/run2.dat''.
 ~L EXPR         message is either originated or received by EXPR
 ~l              message is addressed to a known mailing list
 ~m [MIN]-[MAX]  message in the range MIN to MAX *)
+~M              multipart messages
 ~n [MIN]-[MAX]  messages with a score in the range MIN to MAX *)
 ~N              new messages
 ~O              old messages