From: Kevin McCarthy <kevin@8t8.us>
Date: Mon, 27 Jul 2015 21:09:55 +0000 (-0700)
Subject: Add "Mailbox Matching in Hooks" section to manual.
X-Git-Tag: neomutt-20160307~31
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=d8a7295115120739f816e064b1930929daea9a8d;p=neomutt

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 109bd2db8..b88f8769b 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
@@ -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">