Add "Mailbox Matching in Hooks" section to manual.

Folder-hook and mbox-hook perform mailbox shortcut expansion on the
regexp parameter.  Add a section to the manual to give examples and make
the behavior clearer.

diff --git a/doc/manual.xml.head b/doc/manual.xml.head
index 109bd2db8a7d263c4f79a34a2ef9a2c50cb7a33b..b88f8769bb4e1b41f7d395b8d2ba4632e1dc76cc 100644 (file)
--- a/doc/manual.xml.head
+++ b/doc/manual.xml.head
@@ -2423,6 +2423,12 @@ mailbox matches multiple <command>folder-hook</command>s, they are
 executed in the order given in the <literal>.muttrc</literal>.
 </para>
 
+<para>
+The regexp parameter has <link linkend="shortcuts">mailbox
+shortcut</link> expansion performed on the first character.
+See  <xref linkend="mailbox-hook"/> for more details.
+</para>
+
 <note>
 <para>
 If you use the <quote>!</quote> shortcut for <link
@@ -3202,6 +3208,12 @@ mailbox to treat as a <quote>spool</quote> mailbox and
 read.
 </para>
 
+<para>
+The regexp parameter has <link linkend="shortcuts">mailbox
+shortcut</link> expansion performed on the first character.
+See  <xref linkend="mailbox-hook"/> for more details.
+</para>
+
 <para>
 Unlike some of the other <emphasis>hook</emphasis> commands, only the
 <emphasis>first</emphasis> matching regexp is used (it is not possible
@@ -5575,6 +5587,43 @@ time will be used.
 
 </sect2>
 
+<sect2 id="mailbox-hook" xreflabel="Mailbox Matching in Hooks">
+<title>Mailbox Matching in Hooks</title>
+
+<para>
+Hooks that match against mailboxes (<command>folder-hook</command>,
+<command>mbox-hook</command>) apply both <link linkend="regexp">regular
+expression</link> syntax as well as <link linkend="shortcuts">mailbox
+shortcut</link> expansion on the regexp parameter.  There is some
+overlap between these, so special attention should be paid to the first
+character of the regexp.
+</para>
+
+<screen>
+# Here, ^ will expand to "the current mailbox" not "beginning of string":
+folder-hook ^/home/user/Mail/bar "set sort=threads"
+
+# If you want ^ to be interpreted as "beginning of string", one workaround
+# is to enclose the regexp in parenthesis:
+folder-hook (^/home/user/Mail/bar) "set sort=threads"
+
+# This will expand to the default save folder for the alias "imap.example.com", which
+# is probably not what you want:
+folder-hook @imap.example.com "set sort=threads"
+
+# A workaround is to use parenthesis or a backslash:
+folder-hook (@imap.example.com) "set sort=threads"
+folder-hook \@imap.example.com "set sort=threads"
+</screen>
+
+<para>
+Keep in mind that mailbox shortcut expansion on the regexp parameter
+takes place when the hook is initially parsed, not when the hook is
+matching against a mailbox.
+</para>
+
+</sect2>
+
 </sect1>
 
 <sect1 id="query">