From 75474bbc91dc470f292067ad365d5288c09eb0f2 Mon Sep 17 00:00:00 2001
From: Tomi Ollila <tomi.ollila@iki.fi>
Date: Wed, 20 Oct 2021 19:39:53 +0300
Subject: [PATCH] manpages updates for release 0.34
---
manpages.mdwn | 3 +-
manpages/notmuch-1.mdwn | 2 +-
manpages/notmuch-address-1.mdwn | 2 +-
manpages/notmuch-compact-1.mdwn | 2 +-
manpages/notmuch-config-1.mdwn | 7 +-
manpages/notmuch-count-1.mdwn | 2 +-
manpages/notmuch-dump-1.mdwn | 2 +-
manpages/notmuch-emacs-mua-1.mdwn | 2 +-
manpages/notmuch-hooks-5.mdwn | 2 +-
manpages/notmuch-insert-1.mdwn | 2 +-
manpages/notmuch-new-1.mdwn | 2 +-
manpages/notmuch-properties-7.mdwn | 2 +-
manpages/notmuch-reindex-1.mdwn | 2 +-
manpages/notmuch-reply-1.mdwn | 2 +-
manpages/notmuch-restore-1.mdwn | 2 +-
manpages/notmuch-search-1.mdwn | 2 +-
manpages/notmuch-search-terms-7.mdwn | 2 +-
manpages/notmuch-sexp-queries-7.mdwn | 295 +++++++++++++++++++++++++++
manpages/notmuch-show-1.mdwn | 2 +-
manpages/notmuch-tag-1.mdwn | 2 +-
20 files changed, 320 insertions(+), 19 deletions(-)
create mode 100644 manpages/notmuch-sexp-queries-7.mdwn
diff --git a/manpages.mdwn b/manpages.mdwn
index da4254a..b97fef0 100644
--- 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 0c353ee..19253e3 100644
--- 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 4f5d9b9..1c649c2 100644
--- 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 9d98415..3ee6e2d 100644
--- 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 6ffaba6..bee4eb2 100644
--- a/manpages/notmuch-config-1.mdwn
+++ b/manpages/notmuch-config-1.mdwn
@@ -246,6 +246,11 @@
<b>query.<name></b>
Expansion for named query called <name>. 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.<name></b>
+ Expansion for named query called <name>, 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 ea5a5e1..47dd4fc 100644
--- 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 a97f2d2..ae01270 100644
--- 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 9c200d6..69866ff 100644
--- 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 aa3eee9..e636992 100644
--- 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 41438ad..affbe16 100644
--- 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 dafa56a..69bbc39 100644
--- 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 44d455a..81de197 100644
--- 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 47a3536..12bda60 100644
--- 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 cf63d9a..ed6d311 100644
--- 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 c3943fd..8c173dd 100644
--- 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 35ca05e..18b268e 100644
--- 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 5818d7f..b3561a3 100644
--- 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
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> '(and (to santa) (date
+ december))'
+</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> 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 (") delimit strings possibly containing whitespace
+ or parentheses. These can contain double quote characters by esâ
+ caping with backslash. E.g. <b>"this</b> <b>is</b> <b>a</b> <b>quote</b> <b>\""</b>.
+</pre>
+
+<h3> 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> "*" 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> 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 "Search prefixes" 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> 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> 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>"")</b>.
+</pre>
+
+<h2>EXAMPLES</h2>
+<pre>
+ <b>Wizard</b> Match all messages containing the word "wizard", ignoring case.
+
+ <b>added</b> Match all messages containing "added", but also those containing
+ "add", "additional", "Additional", "adds", etc... via stemming.
+
+ <b>(and</b> <b>Bob</b> <b>Marley)</b>
+ Match messages containing words "Bob" and "Marley", or their
+ stems The words need not be adjacent.
+
+ <b>(not</b> <b>Bob</b> <b>Marley)</b>
+ Match messages containing neither "Bob" nor "Marley", nor their
+ stems,
+
+ <b>"quick</b> <b>fox"</b> <b>quick-fox</b> <b>quick@fox</b>
+ Match the <u>phrase</u> "quick" followed by "fox" 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
+ "<u>1234@invalid</u>"
+
+ <b>(id</b> <b>1234@invalid</b> <b>blah@test)</b>
+ Matches Message-Id "<u>1234@invalid</u>" <u>or</u> Message-Id "<u>blah@test</u>"
+
+ <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 "prelim".
+
+ <b>(subject</b> <b>quick</b> <b>brown</b> <b>fox</b> <b>)</b>
+ Match messages whose subject contains "quick" (anywhere,
+ stemmed) and the phrase "brown fox".
+
+ <b>(subject</b> <b>(starts-with</b> <b>prelim))</b>
+ Matches any word starting with "prelim", 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 "quick brown fox", but
+ also "brown fox quicksand".
+
+ <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
+ "<u>1234@invalid</u>"
+
+ <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 "â
+ <u>bob@example.com</u>" and a (possibly distinct) message to "bob at
+ example.com")
+
+ <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 "To" or "Cc" headers, "<u>bob@example.com</u>", "â
+ <u>mallory@example.org</u>", and also "<u>bob@example.com.au</u>" since it
+ contains the adjacent triple "bob", "example", "com".
+
+ <b>(not</b> <b>(to</b> <b>*))</b>
+ Match messages with an empty or invalid 'To' and 'Cc' 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> MACRO EXAMPLES</h3>
+<pre>
+ A macro that takes two parameters and applies different fields to them.
+
+ $ notmuch config set squery.TagSubject '(macro (tagname subj) (and (tag ,tagname) (subject ,subj)))'
+ $ notmuch search --query=sexp '(TagSubject inbox maildir)'
+
+ Nested macros are allowed.
+
+ $ notmuch config set squery.Inner '(macro (x) (subject ,x))'
+ $ notmuch config set squery.Outer '(macro (x y) (and (tag ,x) (Inner ,y)))'
+ $ notmuch search --query=sexp '(Outer inbox maildir)'
+
+ Parameters can be re-used to reduce boilerplate. Any field, including
+ user defined fields is permitted within a macro.
+
+ $ notmuch config set squery.About '(macro (name) (or (subject ,name) (List ,name)))'
+ $ notmuch search --query=sexp '(About notmuch)'
+</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 fb28d27..74106c1 100644
--- 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 b07bb57..8673f23 100644
--- 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>
--
2.45.2