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.

1 files changed, 49 insertions, 0 deletions

diff --git a/doc/manual.xml.head b/doc/manual.xml.head
index 109bd2db..b88f8769 100644
--- 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
@@ -3203,6 +3209,12 @@ 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
 to save read mail in more than a single mailbox).
@@ -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">