From: David Bremner <david@tethera.net>
To: Jani Nikula <jani@nikula.org>, David Bremner <david@tethera.net>,
	notmuch@notmuchmail.org
Subject: [PATCH 1/3] doc: add details about Xapian search syntax
Date: Sun, 18 Jan 2015 13:59:29 +0100
Message-Id: <1421585971-29949-1-git-send-email-david@tethera.net>
In-Reply-To: <87h9vojsa0.fsf@nikula.org>
References: <87h9vojsa0.fsf@nikula.org>
Precedence: list

Questions related to the way that probabilistic prefixes and phrases
are handled come up quite often and it is nicer to have the documentation self contained.  Hopefully putting it in subsections prevents it from being overwhelming.
---
 doc/man7/notmuch-search-terms.rst | 52 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/doc/man7/notmuch-search-terms.rst b/doc/man7/notmuch-search-terms.rst
index 1acdaa0..52f6804 100644
--- a/doc/man7/notmuch-search-terms.rst
+++ b/doc/man7/notmuch-search-terms.rst
@@ -129,6 +129,58 @@ operators, but will have to be protected from interpretation by the
 shell, (such as by putting quotation marks around any parenthesized
 expression).
 
+Boolean and Probabilistic Prefixes
+----------------------------------
+
+Xapian (and hence notmuch) prefixes are either **boolean**, supporting
+exact matches like "tag:inbox"  or **probabilistic**, supporting a most flexible **term** based searching. The prefixes currently supported by notmuch are as follows.
+
++------------------+-----------------------+
+|Boolean           |Probabilistic          |
++------------------+-----------------------+
+| **tag:** **id:** | **from:** **to:**     |
+|**thread:**       |**subject:**           |
+|**folder:**       |**attachment**         |
+|**path:**         |                       |
+|                  |                       |
++------------------+-----------------------+
+
+Terms and phrases
+-----------------
+
+In general Xapian distinguishes between lists of terms and
+**phrases**. Phrases are indicated by double quotes (but beware you
+probably need to protect those from your shell) and insist that those
+unstemmed words occur in that order. One useful, but initially
+surprising feature is that the following are equivalant ways to write
+the same phrase.
+
+- "a list of words"
+- a-list-of-words
+- a/list/of/words
+- a.list.of.words
+
+Both parenthesised lists of terms and quoted phrases are ok with
+probabilisitic prefixes such as **to:**, **from:**, and **subject:**. In particular
+
+::
+
+   subject:(pizza free)
+
+is equivalent to
+
+::
+
+   subject:pizza and subject:free
+
+Both of these will match a subject "Free Delicious Pizza" while
+
+::
+
+   subject:"pizza free"
+
+will not.
+
 DATE AND TIME SEARCH
 ====================
 
-- 
2.1.4