+<para>
+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 <literal>user_</literal> and can be
+used just like any ordinary configuration or environment
+variable.
+</para>
+
+<para>
+For example, to view the manual, users can either define two
+macros like the following
+</para>
+
+<para>
+
+<screen>
+macro generic <F1> "!less -r /path/to/manual" "Show manual"
+macro pager <F1> "!less -r /path/to/manual" "Show manual"
+</screen>
+
+</para>
+
+<para>
+for <literal>generic</literal>, <literal>pager</literal> and <literal>index</literal>. The alternative is to
+define a custom variable like so:
+</para>
+
+<para>
+
+<screen>
+set user_manualcmd = "!less -r /path/to_manual"
+macro generic <F1> "$user_manualcmd<enter>" "Show manual"
+macro pager <F1> "$user_manualcmd<enter>" "Show manual"
+macro index <F1> "$user_manualcmd<enter>" "Show manual"
+</screen>
+
+</para>
+
+<para>
+to re-use the command sequence as in:
+</para>
+
+<para>
+
+<screen>
+macro index <F2> "$user_manualcmd | grep '\^[ ]\\+~. '" "Show Patterns"
+</screen>
+
+</para>
+
+<para>
+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.
+</para>
+
+<para>
+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 <literal>reset</literal> command.
+</para>
+
+<para>
+The complete removal is done via the <literal>unset</literal> keyword.
+</para>
+
+<para>
+After the following sequence:
+</para>
+
+<para>
+
+<screen>
+set user_foo = 42
+set user_foo = 666
+</screen>
+
+</para>
+
+<para>
+the variable <literal>$user_foo</literal> has a current value of 666 and an
+initial of 42. The query
+</para>
+
+<para>
+
+<screen>
+set ?user_foo
+</screen>
+
+</para>
+
+<para>
+will show 666. After doing the reset via
+</para>
+
+<para>
+
+<screen>
+reset user_foo
+</screen>
+
+</para>
+
+<para>
+a following query will give 42 as the result. After unsetting it
+via
+</para>
+
+<para>
+
+<screen>
+unset user_foo
+</screen>
+
+</para>
+
+<para>
+any query or operation (except the noted expansion within other
+statements) will lead to an error message.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Pre-Defined Variables </title>
+
+<para>
+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
+<literal>muttng_</literal> and are read-only, i.e. they cannot be set, unset or
+reset. The reference chapter lists all available variables.
+</para>
+
+<para>
+<emphasis> Please consult the local copy of your manual for their
+values as they may differ from different manual sources.</emphasis> Where
+the manual is installed in can be queried (already using such a
+variable) by running:
+</para>
+
+<para>
+
+<screen>
+muttng -Q muttng_docdir
+</screen>
+
+</para>
+
+<para>
+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:
+</para>
+
+<para>
+
+<screen>
+set user_manualcmd = '!less -r /path/to_manual'
+</screen>
+
+</para>
+
+<para>
+to:
+</para>
+
+<para>
+
+<screen>
+set user_manualcmd = "!less -r $muttng_docdir/manual.txt"
+</screen>
+
+</para>
+
+<para>
+which works everywhere if a manual is installed.
+</para>
+
+<para>
+Please note that by the type of quoting, muttng determines when
+to expand these values: when it finds double quotes, the value will
+be expanded during reading the setup files but when it finds single
+quotes, it'll expand it at runtime as needed.
+</para>
+
+<para>
+For example, the statement
+</para>
+
+<para>
+
+<screen>
+folder-hook . "set user_current_folder = $muttng_folder_name"
+</screen>
+
+</para>
+
+<para>
+will be already be translated to the following when reading the
+startup files:
+</para>
+
+<para>
+
+<screen>
+folder-hook . "set user_current_folder = some_folder"
+</screen>
+
+</para>
+
+<para>
+with <literal>some_folder</literal> being the name of the first folder muttng
+opens. On the contrary,
+</para>
+
+<para>
+
+<screen>
+folder-hook . 'set user_current_folder = $muttng_folder_name'
+</screen>
+
+</para>
+
+<para>
+will be executed at runtime because of the single quotes so that
+<literal>user_current_folder</literal> will always have the value of the currently
+opened folder.
+</para>
+
+<para>
+A more practical example is:
+</para>
+
+<para>
+
+<screen>
+folder-hook . 'source ~/.mutt/score-$muttng_folder_name'
+</screen>
+
+</para>
+
+<para>
+which can be used to source files containing score commands
+depending on the folder the user enters.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Type Conversions </title>
+
+<para>
+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):
+</para>
+
+<para>
+
+<screen>
+set read_inc = 100
+set folder = $read_inc
+set read_inc = $folder
+set user_magic_number = 42
+set folder = $user_magic_number
+</screen>
+
+</para>
+
+</sect2>
+
+</sect1>
+
+<sect1 id="alias">
+<title>Defining/Using aliases </title>
+
+<para>
+Usage: <literal>alias</literal> <emphasis>key</emphasis> <emphasis>address</emphasis> [ , <emphasis>address</emphasis>, ... ]
+</para>
+
+<para>
+It's usually very cumbersome to remember or type out the address of someone
+you are communicating with. Mutt-ng allows you to create ``aliases'' which map
+a short string to a full address.
+</para>
+
+<para>
+<emphasis role="bold">Note:</emphasis> if you want to create an alias for a group (by specifying more than
+one address), you <emphasis role="bold">must</emphasis> separate the addresses with a comma (``,'').
+</para>
+
+<para>
+To remove an alias or aliases (``*'' means all aliases):
+</para>
+
+<para>
+<literal>unalias</literal> [ * | <emphasis>key</emphasis> <emphasis>...</emphasis> ]
+</para>
+
+<para>
+
+<screen>
+alias muttdude me@cs.hmc.edu (Michael Elkins)
+alias theguys manny, moe, jack
+</screen>
+
+</para>
+
+<para>
+Unlike other mailers, Mutt-ng doesn't require aliases to be defined
+in a special file. The <literal>alias</literal> command can appear anywhere in
+a configuration file, as long as this file is <link linkend="source">source</link>. Consequently, you can have multiple alias files, or
+you can have all aliases defined in your muttrc.
+</para>
+
+<para>
+On the other hand, the <link linkend="create-alias">create-alias</link>
+function can use only one file, the one pointed to by the <link linkend="alias-file">alias-file</link> variable (which is
+<literal>˜/.muttrc</literal> by default). This file is not special either,
+in the sense that Mutt-ng will happily append aliases to any file, but in
+order for the new aliases to take effect you need to explicitly <link linkend="source">source</link> this file too.
+</para>
+
+<para>
+For example:
+</para>
+
+<para>
+
+<screen>
+source /usr/local/share/Mutt-ng.aliases
+source ~/.mail_aliases
+set alias_file=~/.mail_aliases
+</screen>
+
+</para>
+
+<para>
+To use aliases, you merely use the alias at any place in mutt where mutt
+prompts for addresses, such as the <emphasis>To:</emphasis> or <emphasis>Cc:</emphasis> prompt. You can
+also enter aliases in your editor at the appropriate headers if you have the
+<link linkend="edit-headers">edit-headers</link> variable set.
+</para>
+
+<para>
+In addition, at the various address prompts, you can use the tab character
+to expand a partial alias to the full alias. If there are multiple matches,
+mutt will bring up a menu with the matching aliases. In order to be
+presented with the full list of aliases, you must hit tab with out a partial
+alias, such as at the beginning of the prompt or after a comma denoting
+multiple addresses.
+</para>
+
+<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.
+</para>
+
+<para>
+
+</para>
+
+</sect1>
+
+<sect1 id="bind">
+<title>Changing the default key bindings </title>
+
+<para>
+Usage: <literal>bind</literal> <emphasis>map</emphasis> <emphasis>key</emphasis> <emphasis>function</emphasis>
+</para>
+
+<para>
+This command allows you to change the default key bindings (operation
+invoked when pressing a key).
+</para>
+
+<para>
+<emphasis>map</emphasis> specifies in which menu the binding belongs. Multiple maps may
+be specified by separating them with commas (no additional whitespace is
+allowed). The currently defined maps are:
+</para>
+
+<para>
+<anchor id="maps"/>
+<variablelist>
+
+<varlistentry>
+<term>generic</term>
+<listitem>
+<para>
+This is not a real menu, but is used as a fallback for all of the other
+menus except for the pager and editor modes. If a key is not defined in
+another menu, Mutt-ng will look for a binding to use in this menu. This allows
+you to bind a key to a certain function in multiple menus instead of having
+multiple bind statements to accomplish the same task.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term>alias</term>
+<listitem>
+<para>
+The alias menu is the list of your personal aliases as defined in your
+muttrc. It is the mapping from a short alias name to the full email
+address(es) of the recipient(s).
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term>attach</term>
+<listitem>
+<para>
+The attachment menu is used to access the attachments on received messages.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term>browser</term>
+<listitem>
+<para>
+The browser is used for both browsing the local directory structure, and for
+listing all of your incoming mailboxes.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term>editor</term>
+<listitem>
+<para>
+The editor is the line-based editor the user enters text data.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term>index</term>
+<listitem>
+<para>
+The index is the list of messages contained in a mailbox.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term>compose</term>
+<listitem>
+<para>
+The compose menu is the screen used when sending a new message.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term>pager</term>
+<listitem>
+<para>
+The pager is the mode used to display message/attachment data, and help
+listings.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term>pgp</term>
+<listitem>
+<para>
+The pgp menu is used to select the OpenPGP keys used for encrypting outgoing
+messages.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term>postpone</term>
+<listitem>
+<para>
+The postpone menu is similar to the index menu, except is used when
+recalling a message the user was composing, but saved until later.
+</para>
+</listitem></varlistentry>
+</variablelist>
+</para>
+
+<para>
+<emphasis>key</emphasis> is the key (or key sequence) you wish to bind. To specify a
+control character, use the sequence <emphasis>\Cx</emphasis>, where <emphasis>x</emphasis> is the
+letter of the control character (for example, to specify control-A use
+``\Ca''). Note that the case of <emphasis>x</emphasis> as well as <emphasis>\C</emphasis> is
+ignored, so that <emphasis>\CA</emphasis>, <emphasis>\Ca</emphasis>, <emphasis>\cA</emphasis> and <emphasis>\ca</emphasis> are all
+equivalent. An alternative form is to specify the key as a three digit
+octal number prefixed with a ``\'' (for example <emphasis>\177</emphasis> is
+equivalent to <emphasis>\c?</emphasis>).
+</para>
+
+<para>
+In addition, <emphasis>key</emphasis> may consist of:
+</para>
+
+<para>
+
+<screen>
+\t tab
+<tab> tab
+<backtab> backtab / shift-tab
+\r carriage return
+\n newline
+\e escape
+<esc> escape
+<up> up arrow
+<down> down arrow
+<left> left arrow
+<right> right arrow
+<pageup> Page Up
+<pagedown> Page Down
+<backspace> Backspace
+<delete> Delete
+<insert> Insert
+<enter> Enter
+<return> Return
+<home> Home
+<end> End
+<space> Space bar
+<f1> function key 1
+<f10> function key 10
+</screen>
+
+</para>
+
+<para>
+<emphasis>key</emphasis> does not need to be enclosed in quotes unless it contains a
+space (`` '').
+</para>
+
+<para>
+<emphasis>function</emphasis> specifies which action to take when <emphasis>key</emphasis> is pressed.
+For a complete list of functions, see the <link linkend="functions">functions</link>. The special function <literal>noop</literal> unbinds the specified key
+sequence.
+</para>
+
+<para>
+
+</para>
+
+</sect1>