manpages updates for release 0.34

diff --git a/manpages.mdwn b/manpages.mdwn
index da4254a3ebad0be7958fc3c3d555b41548517ff5..b97fef0131ea7d76c03a4b8e8c6dbbca5e2b2af0 100644 (file)
--- a/manpages.mdwn
+++ b/manpages.mdwn
@@ -19,9 +19,10 @@ Manual page index
 * <a href='notmuch-hooks-5/'>notmuch-hooks</a>(5) - hooks for notmuch
 * <a href='notmuch-properties-7/'>notmuch-properties</a>(7) - notmuch message property conventions and documentation
 * <a href='notmuch-search-terms-7/'>notmuch-search-terms</a>(7) - syntax for notmuch queries
+* <a href='notmuch-sexp-queries-7/'>notmuch-sexp-queries</a>(7) - s-expression syntax for notmuch queries
 
 The manual pages are licensed under
 [the GNU General Public License](https://www.gnu.org/licenses/gpl.txt),
 either version 3.0 or at your option any later version.
 
-<h2>0.33</h2>
+<h2>0.34</h2>

diff --git a/manpages/notmuch-1.mdwn b/manpages/notmuch-1.mdwn
index 0c353eeb0ae3c1c5ee5f5861a4893828ce910182..19253e3e2d5d280ee85f18e6c2c3c2ed4e5680c3 100644 (file)
--- a/manpages/notmuch-1.mdwn
+++ b/manpages/notmuch-1.mdwn
@@ -196,4 +196,4 @@
        2009-2021, Carl Worth and many others
 </pre>
 
-<h2>0.33</h2>
+<h2>0.34</h2>

diff --git a/manpages/notmuch-address-1.mdwn b/manpages/notmuch-address-1.mdwn
index 4f5d9b93554dbd93c1072bc93fd09eab1bbf0943..1c649c2752eee0ad36e860e68503986b9b0fa106 100644 (file)
--- a/manpages/notmuch-address-1.mdwn
+++ b/manpages/notmuch-address-1.mdwn
@@ -130,4 +130,4 @@
        2009-2021, Carl Worth and many others
 </pre>
 
-<h2>0.33</h2>
+<h2>0.34</h2>

diff --git a/manpages/notmuch-compact-1.mdwn b/manpages/notmuch-compact-1.mdwn
index 9d98415564441699d808d224afc81d492d299bd6..3ee6e2ddc208ea87438b605f1038c82e60a6fabb 100644 (file)
--- a/manpages/notmuch-compact-1.mdwn
+++ b/manpages/notmuch-compact-1.mdwn
@@ -53,4 +53,4 @@
        2009-2021, Carl Worth and many others
 </pre>
 
-<h2>0.33</h2>
+<h2>0.34</h2>

diff --git a/manpages/notmuch-config-1.mdwn b/manpages/notmuch-config-1.mdwn
index 6ffaba62603c51b4cd846b594db3d82dce846d06..bee4eb2d3187a8bee237f4420804541ea973a222 100644 (file)
--- a/manpages/notmuch-config-1.mdwn
+++ b/manpages/notmuch-config-1.mdwn
@@ -246,6 +246,11 @@
        <b>query.&lt;name&gt;</b>
               Expansion   for   named   query   called   &lt;name&gt;.   See    <a href='../notmuch-search-terms-7/'>not‐</a>
               <a href='../notmuch-search-terms-7/'>much-search-terms</a>(7) for more information about named queries.
+
+       <b>squery.&lt;name&gt;</b>
+              Expansion for named query called &lt;name&gt;, using s-expression syn‐
+              tax. See  <a href='../notmuch-sexp-queries-7/'>notmuch-sexp-queries</a>(7)  for  more  information  about
+              s-expression queries.
 </pre>
 
 <h2>FILES</h2>
@@ -315,4 +320,4 @@
        2009-2021, Carl Worth and many others
 </pre>
 
-<h2>0.33</h2>
+<h2>0.34</h2>

diff --git a/manpages/notmuch-count-1.mdwn b/manpages/notmuch-count-1.mdwn
index ea5a5e1578e61e73cfeb162b79073e29f73c9f23..47dd4fcda413984c9ede6b1e01c16f3ee125aac3 100644 (file)
--- a/manpages/notmuch-count-1.mdwn
+++ b/manpages/notmuch-count-1.mdwn
@@ -77,4 +77,4 @@
        2009-2021, Carl Worth and many others
 </pre>
 
-<h2>0.33</h2>
+<h2>0.34</h2>

diff --git a/manpages/notmuch-dump-1.mdwn b/manpages/notmuch-dump-1.mdwn
index a97f2d2ecfd659220fff3011ce364387ca0eaec1..ae0127054123e22995124ee2afcaab8b1e84b170 100644 (file)
--- a/manpages/notmuch-dump-1.mdwn
+++ b/manpages/notmuch-dump-1.mdwn
@@ -117,4 +117,4 @@
        2009-2021, Carl Worth and many others
 </pre>
 
-<h2>0.33</h2>
+<h2>0.34</h2>

diff --git a/manpages/notmuch-emacs-mua-1.mdwn b/manpages/notmuch-emacs-mua-1.mdwn
index 9c200d6dca415c72a2a11c608c80e28b2a9963cd..69866ff883998d56a44521a04234df64f53aa098 100644 (file)
--- a/manpages/notmuch-emacs-mua-1.mdwn
+++ b/manpages/notmuch-emacs-mua-1.mdwn
@@ -92,4 +92,4 @@
        2009-2021, Carl Worth and many others
 </pre>
 
-<h2>0.33</h2>
+<h2>0.34</h2>

diff --git a/manpages/notmuch-hooks-5.mdwn b/manpages/notmuch-hooks-5.mdwn
index aa3eee9dceaa8c0527881309f31902b45878791b..e6369929a3afa8d958e937e20397f8162d76fc15 100644 (file)
--- a/manpages/notmuch-hooks-5.mdwn
+++ b/manpages/notmuch-hooks-5.mdwn
@@ -66,4 +66,4 @@
        2009-2021, Carl Worth and many others
 </pre>
 
-<h2>0.33</h2>
+<h2>0.34</h2>

diff --git a/manpages/notmuch-insert-1.mdwn b/manpages/notmuch-insert-1.mdwn
index 41438ad6e74ab1bf596f0de065c3c6bae962cf99..affbe16e34310c04b92a85f8c31f23eeaff5889c 100644 (file)
--- a/manpages/notmuch-insert-1.mdwn
+++ b/manpages/notmuch-insert-1.mdwn
@@ -116,4 +116,4 @@
        2009-2021, Carl Worth and many others
 </pre>
 
-<h2>0.33</h2>
+<h2>0.34</h2>

diff --git a/manpages/notmuch-new-1.mdwn b/manpages/notmuch-new-1.mdwn
index dafa56a5cdcf0e863b715407be30b4184705c09e..69bbc399f5eb79b8da82117dd49f8949cac7988b 100644 (file)
--- a/manpages/notmuch-new-1.mdwn
+++ b/manpages/notmuch-new-1.mdwn
@@ -95,4 +95,4 @@
        2009-2021, Carl Worth and many others
 </pre>
 
-<h2>0.33</h2>
+<h2>0.34</h2>

diff --git a/manpages/notmuch-properties-7.mdwn b/manpages/notmuch-properties-7.mdwn
index 44d455a4f4147e12d7a30b9d82401ce145c48baa..81de1973c821d5ef752fb4ea83c0928afee8cbbb 100644 (file)
--- a/manpages/notmuch-properties-7.mdwn
+++ b/manpages/notmuch-properties-7.mdwn
@@ -148,4 +148,4 @@
        2009-2021, Carl Worth and many others
 </pre>
 
-<h2>0.33</h2>
+<h2>0.34</h2>

diff --git a/manpages/notmuch-reindex-1.mdwn b/manpages/notmuch-reindex-1.mdwn
index 47a35365e39a7c766ec07fcf48df606e7ca0c9b4..12bda6050e305cda911ecb45f2999d7dd503eb13 100644 (file)
--- a/manpages/notmuch-reindex-1.mdwn
+++ b/manpages/notmuch-reindex-1.mdwn
@@ -94,4 +94,4 @@
        2009-2021, Carl Worth and many others
 </pre>
 
-<h2>0.33</h2>
+<h2>0.34</h2>

diff --git a/manpages/notmuch-reply-1.mdwn b/manpages/notmuch-reply-1.mdwn
index cf63d9a5315888cea8c431281ee8a0593122b9b4..ed6d3114227b9e7addde1d6af6721d16a9e33464 100644 (file)
--- a/manpages/notmuch-reply-1.mdwn
+++ b/manpages/notmuch-reply-1.mdwn
@@ -130,4 +130,4 @@
        2009-2021, Carl Worth and many others
 </pre>
 
-<h2>0.33</h2>
+<h2>0.34</h2>

diff --git a/manpages/notmuch-restore-1.mdwn b/manpages/notmuch-restore-1.mdwn
index c3943fdc797cff6b3b75a6df6e270b8a474546bd..8c173dd2049fa4e8310c1d59b7873f8de23a80b9 100644 (file)
--- a/manpages/notmuch-restore-1.mdwn
+++ b/manpages/notmuch-restore-1.mdwn
@@ -102,4 +102,4 @@
        2009-2021, Carl Worth and many others
 </pre>
 
-<h2>0.33</h2>
+<h2>0.34</h2>

diff --git a/manpages/notmuch-search-1.mdwn b/manpages/notmuch-search-1.mdwn
index 35ca05ed064daaf2db57d92f66ecee3fbd4f0a90..18b268e285000075eb26f27367ffe74524ac3a2f 100644 (file)
--- a/manpages/notmuch-search-1.mdwn
+++ b/manpages/notmuch-search-1.mdwn
@@ -179,4 +179,4 @@
        2009-2021, Carl Worth and many others
 </pre>
 
-<h2>0.33</h2>
+<h2>0.34</h2>

diff --git a/manpages/notmuch-search-terms-7.mdwn b/manpages/notmuch-search-terms-7.mdwn
index 5818d7f7ea0ca716e7ec3e6ac46621728f71a2a9..b3561a3c52b154330eb9df8ceafd48e5da6db03e 100644 (file)
--- a/manpages/notmuch-search-terms-7.mdwn
+++ b/manpages/notmuch-search-terms-7.mdwn
@@ -435,4 +435,4 @@
        2009-2021, Carl Worth and many others
 </pre>
 
-<h2>0.33</h2>
+<h2>0.34</h2>

diff --git a/manpages/notmuch-sexp-queries-7.mdwn b/manpages/notmuch-sexp-queries-7.mdwn
new file mode 100644 (file)
index 0000000..6744e91
--- /dev/null
+++ b/manpages/notmuch-sexp-queries-7.mdwn
@@ -0,0 +1,295 @@
+<h1>NOTMUCH-SEXP-QUERIES(7)</h1>
+
+<h2>NAME</h2>
+<pre>
+       notmuch-sexp-queries - s-expression syntax for notmuch queries
+</pre>
+
+<h2>SYNOPSIS</h2>
+<pre>
+       <b>notmuch</b> <u>subcommand</u> <b>--query=sexp</b> [option ...]  <b>--</b> &apos;(and (to santa) (date
+       december))&apos;
+</pre>
+
+<h2>DESCRIPTION</h2>
+<pre>
+       Notmuch supports an alternative query syntax based on  <u>S-expressions</u>  .
+       It  can  be selected with the command line <b>--query=sexp</b> or with the ap‐
+       propriate option to the library function <b>notmuch</b>_<b>query</b>_<b>create</b>_<b>with</b>_<b>syn-</b>
+       <b>tax()</b>.   Support for this syntax is currently optional, you can test if
+       your build of notmuch supports it with
+
+          $ notmuch config get built_with.sexpr_query
+</pre>
+
+<h3> &nbsp; S-EXPRESSIONS</h3>
+<pre>
+       An <u>s-expression</u> is either an atom,  or  list  of  whitespace  delimited
+       s-expressions inside parentheses. Atoms are either
+
+       <u>basic</u> <u>value</u>
+              A  basic  value  is an unquoted string containing no whitespace,
+              double quotes, or parentheses.
+
+       <u>quoted</u> <u>string</u>
+              Double quotes (&quot;) delimit strings possibly containing whitespace
+              or parentheses. These can contain double quote characters by es‐
+              caping with backslash. E.g. <b>&quot;this</b> <b>is</b> <b>a</b> <b>quote</b> <b>\&quot;&quot;</b>.
+</pre>
+
+<h3> &nbsp; S-EXPRESSION QUERIES</h3>
+<pre>
+       An s-expression query is either an atom, the empty list, or a  <u>compound</u>
+       <u>query</u>  consisting  of  a  prefix atom (first element) defining a <u>field</u>,
+       <u>logical</u> <u>operation</u>, or <u>modifier</u>, and 0 or more subqueries.
+
+       <b>*</b>      &quot;*&quot; matches any non-empty string in the current field.
+
+       <b>()</b>     The empty list matches all messages
+
+       <u>term</u>
+          Match all messages  containing  <u>term</u>,  possibly  after  stemming  or
+          phrase  splitting.  For  discussion  of stemming in notmuch see <a href='../notmuch-search-terms-7/'>not‐</a>
+          <a href='../notmuch-search-terms-7/'>much-search-terms</a>(7). Stemming only applies to unquoted terms (basic
+          values)  in  s-expression queries.  For information on phrase split‐
+          ting see <u>FIELDS</u>.
+
+       <b>(</b> <u>field</u> <b>q</b>_<b>1</b> <b>q</b>_<b>2</b> <b>...</b> <b>q</b>_<b>n</b> <b>)</b>
+              Restrict the queries q_1 to q_n to <u>field</u>, and combine  with  <u>and</u>
+              (for most fields) or <u>or</u>. See <u>FIELDS</u> for more information.
+
+       <b>(</b> <u>operator</u> <b>q</b>_<b>1</b> <b>q</b>_<b>2</b> <b>...</b> <b>q</b>_<b>n</b> <b>)</b>
+              Combine  queries  q_1  to q_n. Currently supported operators are
+              <b>and</b>, <b>or</b>, and <b>not</b>. <b>(not</b> q_1 ... q_n <b>)</b> is equivalent to <b>(and</b>  <b>(not</b>
+              q_1 <b>)</b> <b>...</b> <b>(not</b> q_n <b>))</b>.
+
+       <b>(</b> <u>modifier</u> <b>q</b>_<b>1</b> <b>q</b>_<b>2</b> <b>...</b> <b>q</b>_<b>n</b> <b>)</b>
+              Combine  queries q_1 to q_n, and reinterpret the result (e.g. as
+              a regular expression).  See <u>MODIFIERS</u> for more information.
+
+       <b>(macro</b> <b>(</b> <b>p</b>_<b>1</b> <b>...</b> <b>p</b>_<b>n</b> <b>)</b> <b>body)</b>
+              Define saved query with parameter substitution.  The  syntax  is
+              recognized  only  in saved s-expression queries (see <b>squery.*</b> in
+              <a href='../notmuch-config-1/'>notmuch-config</a>(1)). Parameter names in  <b>body</b>  must  be  prefixed
+              with <b>,</b> to be expanded (see <u>MACRO</u> <u>EXAMPLES</u>).  Macros may refer to
+              other macros, but only to their own parameters [1].
+</pre>
+
+<h3> &nbsp; FIELDS</h3>
+<pre>
+       <u>Fields</u> [2] correspond to attributes of mail messages. Some are inherent
+       (and  immutable)  like  <b>subject</b>, while others <b>tag</b> and <b>property</b> are set‐
+       table by the user.  Each concrete field in <u>the</u> <u>table</u> <u>below</u> is discussed
+       further  under  &quot;Search  prefixes&quot;  in <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7). The row
+       <u>user</u> refers to user defined fields, described in <a href='../notmuch-config-1/'>notmuch-config</a>(1).
+
+       Most fields are either <u>phrase</u> <u>fields</u>  [3]  (which  match  sequences  of
+       words),  or  <u>term</u> <u>fields</u> [4] (which match exact strings). <u>Phrase</u> <u>split‐</u>
+       <u>ting</u> breaks the term (basic value or quoted string) into words,  ignore
+       punctuation.  Phrase  splitting  is  applied to terms in phrase (proba‐
+       bilistic) fields. Both phrase splitting  and  stemming  apply  only  in
+       phrase fields.
+
+       Each  term or phrase field has an associated combining operator (<b>and</b> or
+       <b>or</b>) used to combine the queries from each element of the  tail  of  the
+       list.  This  is  generally  <b>or</b> for those fields where a message has one
+       such attribute, and <b>and</b> otherwise.
+
+       Term or phrase fields can contain arbitrarily complex queries  made  up
+       from terms, operators, and modifiers, but not other fields.
+</pre>
+
+<h3> &nbsp; Fields with supported modifiers</h3>
+<pre>
+             ┌───────────┬─────────┬────────┬────────┬──────────┬───────┐
+             │field      │ combine │ type   │ expand │ wildcard │ regex │
+             ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
+             │<u>none</u>       │ and     │        │ no     │ yes      │ no    │
+             ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
+             │<u>user</u>       │ and     │ phrase │ no     │ yes      │ no    │
+             ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
+             │attachment │ and     │ phrase │ yes    │ yes      │ no    │
+             ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
+             │body       │ and     │ phrase │ no     │ no       │ no    │
+             ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
+             │date       │         │ range  │ no     │ no       │ no    │
+             ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
+             │folder     │ or      │ phrase │ yes    │ yes      │ yes   │
+             ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
+             │from       │ and     │ phrase │ yes    │ yes      │ yes   │
+             ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
+             │id         │ or      │ term   │ no     │ yes      │ yes   │
+             ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
+             │is         │ and     │ term   │ yes    │ yes      │ yes   │
+             ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
+             │lastmod    │         │ range  │ no     │ no       │ no    │
+             ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
+             │mid        │ or      │ term   │ no     │ yes      │ yes   │
+             ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
+             │mimetype   │ or      │ phrase │ yes    │ yes      │ no    │
+             ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
+             │path       │ or      │ term   │ no     │ yes      │ yes   │
+             ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
+             │property   │ and     │ term   │ yes    │ yes      │ yes   │
+             ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
+             │subject    │ and     │ phrase │ yes    │ yes      │ yes   │
+             ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
+             │tag        │ and     │ term   │ yes    │ yes      │ yes   │
+             ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
+             │thread     │ or      │ term   │ yes    │ yes      │ yes   │
+             ├───────────┼─────────┼────────┼────────┼──────────┼───────┤
+             │to         │ and     │ phrase │ yes    │ yes      │ no    │
+             └───────────┴─────────┴────────┴────────┴──────────┴───────┘
+</pre>
+
+<h3> &nbsp; MODIFIERS</h3>
+<pre>
+       <u>Modifiers</u>  refer  to  any prefixes (first elements of compound queries)
+       that are neither operators nor fields.
+
+       <b>(infix</b> <u>atom</u> <b>)</b>
+              Interpret  <u>atom</u>  as   an   infix   notmuch   query   (see   <a href='../notmuch-search-terms-7/'>not‐</a>
+              <a href='../notmuch-search-terms-7/'>much-search-terms</a>(7)). Not supported inside fields.
+
+       <b>(matching</b> <b>q</b>_<b>1</b> <b>q</b>_<b>2</b> <b>...</b> <b>q</b>_<b>n</b> <b>)</b> <b>(of</b> <b>q</b>_<b>1</b> <b>q</b>_<b>2</b> <b>...</b> <b>q</b>_<b>n</b> <b>)</b>
+              Match  all messages have the same values of the current field as
+              those matching all of q_1 ... q_n. Supported in most term [7] or
+              phrase fields. Most commonly used in the <b>thread</b> field.
+
+       <b>(query</b> <u>atom</u> <b>)</b>
+              Expand  to  the saved query named by <u>atom</u>. See <a href='../notmuch-config-1/'>notmuch-config</a>(1)
+              for more. Note that the saved query  must  be  in  infix  syntax
+              (<a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7)). Not supported inside fields.
+
+       <b>(regex</b> <u>atom</u> <b>)</b> <b>(rx</b> <u>atom</u> <b>)</b>
+              Interpret  <u>atom</u>  as a POSIX.2 regular expression (see <b>regex</b>(7)).
+              This applies in term fields and a subset [5]  of  phrase  fields
+              (see <u>Fields</u> <u>with</u> <u>supported</u> <u>modifiers</u>).
+
+       <b>(starts-with</b> <u>subword</u> <b>)</b>
+              Matches  any term starting with <u>subword</u>.  This applies in either
+              phrase or term <u>fields</u>, or outside of fields  [6].  Note  that  a
+              <b>starts-with</b>  query  cannot  be part of a phrase. The atom <b>*</b> is a
+              synonym for <b>(starts-with</b> <b>&quot;&quot;)</b>.
+</pre>
+
+<h2>EXAMPLES</h2>
+<pre>
+       <b>Wizard</b> Match all messages containing the word &quot;wizard&quot;, ignoring case.
+
+       <b>added</b>  Match all messages containing &quot;added&quot;, but also those containing
+              &quot;add&quot;, &quot;additional&quot;, &quot;Additional&quot;, &quot;adds&quot;, etc... via stemming.
+
+       <b>(and</b> <b>Bob</b> <b>Marley)</b>
+              Match  messages  containing  words  &quot;Bob&quot; and &quot;Marley&quot;, or their
+              stems The words need not be adjacent.
+
+       <b>(not</b> <b>Bob</b> <b>Marley)</b>
+              Match messages containing neither &quot;Bob&quot; nor &quot;Marley&quot;, nor  their
+              stems,
+
+       <b>&quot;quick</b> <b>fox&quot;</b> <b>quick-fox</b> <b>quick@fox</b>
+              Match  the <u>phrase</u> &quot;quick&quot; followed by &quot;fox&quot; in phrase fields (or
+              outside a field). Match the literal string in a term field.
+
+       <b>(folder</b> <b>(of</b> <b>(id</b> <b>1234@invalid)))</b>
+              Match any message in the same folder as the one with  Message-Id
+              &quot;<u>1234@invalid</u>&quot;
+
+       <b>(id</b> <b>1234@invalid</b> <b>blah@test)</b>
+              Matches Message-Id &quot;<u>1234@invalid</u>&quot; <u>or</u> Message-Id &quot;<u>blah@test</u>&quot;
+
+       <b>(and</b> <b>(infix</b> <b>date:2009-11-18..2009-11-18</b> <b>)</b> <b>(tag</b> <b>unread))</b>
+              Match messages in the given date range with tag unread.
+
+       <b>(starts-with</b> <b>prelim)</b>
+              Match any words starting with &quot;prelim&quot;.
+
+       <b>(subject</b> <b>quick</b> <b>brown</b> <b>fox</b> <b>)</b>
+              Match   messages   whose  subject  contains  &quot;quick&quot;  (anywhere,
+              stemmed) and the phrase &quot;brown fox&quot;.
+
+       <b>(subject</b> <b>(starts-with</b> <b>prelim))</b>
+              Matches any word starting with &quot;prelim&quot;, inside a  message  sub‐
+              ject.
+
+       <b>(subject</b> <b>(starts-wih</b> <b>quick)</b> <b>brown</b> <b>fox</b> <b>)</b>
+              Match  messages  whose  subject  contains &quot;quick brown fox&quot;, but
+              also &quot;brown fox quicksand&quot;.
+
+       <b>(thread</b> <b>(of</b> <b>(id</b> <b>1234@invalid)))</b>
+              Match any message in the same thread as the one with  Message-Id
+              &quot;<u>1234@invalid</u>&quot;
+
+       <b>(thread</b> <b>(matching</b> <b>(from</b> <b>bob@example.com)</b> <b>(to</b> <b>bob@example.com)))</b>
+              Match  any  (messages  in) a thread containing a message from &quot;‐
+              <u>bob@example.com</u>&quot; and a (possibly distinct) message  to  &quot;bob  at
+              example.com&quot;)
+
+       <b>(to</b>  <b>(or</b> <b>bob@example.com</b> <b>mallory@example.org))</b> <b>(or</b> <b>(to</b> <b>bob@example.com)</b>
+       <b>(to</b> <b>mallory@example.org))</b>
+              Match  in  the  &quot;To&quot;  or  &quot;Cc&quot;  headers,  &quot;<u>bob@example.com</u>&quot;,  &quot;‐
+              <u>mallory@example.org</u>&quot;,  and  also  &quot;<u>bob@example.com.au</u>&quot;  since it
+              contains the adjacent triple &quot;bob&quot;, &quot;example&quot;, &quot;com&quot;.
+
+       <b>(not</b> <b>(to</b> <b>*))</b>
+              Match messages with an empty or invalid &apos;To&apos; and &apos;Cc&apos; field.
+
+       <b>(List</b> <b>*)</b>
+              Match messages with a non-empty List-Id header, assuming config‐
+              uration <b>index.header.List=List-Id</b>
+</pre>
+
+<h3> &nbsp; MACRO EXAMPLES</h3>
+<pre>
+       A macro that takes two parameters and applies different fields to them.
+
+          $ notmuch config set squery.TagSubject &apos;(macro (tagname subj) (and (tag ,tagname) (subject ,subj)))&apos;
+          $ notmuch search --query=sexp &apos;(TagSubject inbox maildir)&apos;
+
+       Nested macros are allowed.
+
+          $ notmuch config set squery.Inner &apos;(macro (x) (subject ,x))&apos;
+          $ notmuch config set squery.Outer  &apos;(macro (x y) (and (tag ,x) (Inner ,y)))&apos;
+          $ notmuch search --query=sexp &apos;(Outer inbox maildir)&apos;
+
+       Parameters  can  be re-used to reduce boilerplate. Any field, including
+       user defined fields is permitted within a macro.
+
+          $ notmuch config set squery.About &apos;(macro (name) (or (subject ,name) (List ,name)))&apos;
+          $ notmuch search --query=sexp &apos;(About notmuch)&apos;
+</pre>
+
+<h2>NOTES</h2>
+<pre>
+       [1]  Technically macros impliment lazy evaluation  and  lexical  scope.
+            There is one top level scope containing all macro definitions, but
+            all parameter definitions are local to a given macro.
+
+       [2]  a.k.a. prefixes
+
+       [3]  a.k.a. probabilistic prefixes
+
+       [4]  a.k.a. boolean prefixes
+
+       [5]  Due to the implemention of phrase fields in Xapian, regex  queries
+            could only match individual words.
+
+       [6]  Due  the  the way <b>body</b> is implemented in notmuch, this modifier is
+            not supported in the <b>body</b> field.
+
+       [7]  Due to the way recursive <b>path</b> queries are implemented in  notmuch,
+            this modifier is not supported in the <b>path</b> field.
+</pre>
+
+<h2>AUTHOR</h2>
+<pre>
+       Carl Worth and many others
+</pre>
+
+<h2>COPYRIGHT</h2>
+<pre>
+       2009-2021, Carl Worth and many others
+</pre>
+
+<h2>0.34</h2>

diff --git a/manpages/notmuch-show-1.mdwn b/manpages/notmuch-show-1.mdwn
index fb28d27b2717ae9905914a22c480e3882586de2d..74106c112d0e27b6acacc943b0454fe24d4f893f 100644 (file)
--- a/manpages/notmuch-show-1.mdwn
+++ b/manpages/notmuch-show-1.mdwn
@@ -237,4 +237,4 @@
        2009-2021, Carl Worth and many others
 </pre>
 
-<h2>0.33</h2>
+<h2>0.34</h2>

diff --git a/manpages/notmuch-tag-1.mdwn b/manpages/notmuch-tag-1.mdwn
index b07bb572cb112d286e279e74b34dc638dd980ab4..8673f231752a05d65b2cb9b25e99714769143da5 100644 (file)
--- a/manpages/notmuch-tag-1.mdwn
+++ b/manpages/notmuch-tag-1.mdwn
@@ -116,4 +116,4 @@
        2009-2021, Carl Worth and many others
 </pre>
 
-<h2>0.33</h2>
+<h2>0.34</h2>