[PATCH] doc: add details about Xapian search syntax

[Jani Nikula]

On Sun, 18 Jan 2015, David Bremner <david at tethera.net> wrote:
> 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.

I think this is a good idea.

> ---
>  doc/man7/notmuch-search-terms.rst | 46 +++++++++++++++++++++++++++++++++++++++
>  1 file changed, 46 insertions(+)
>
> diff --git a/doc/man7/notmuch-search-terms.rst b/doc/man7/notmuch-search-terms.rst
> index 1acdaa0..5c65938 100644
> --- a/doc/man7/notmuch-search-terms.rst
> +++ b/doc/man7/notmuch-search-terms.rst
> @@ -129,6 +129,52 @@ 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 pre

The pre?

> +
> ++------------------+-----------------------+
> +|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.
> +

While at it, I think it would be useful to incorporate relevant parts of
http://notmuchmail.org/searching/ into the man page.

BR,
Jani.


>  DATE AND TIME SEARCH
>  ====================
>  
> -- 
> 2.1.4
>
> _______________________________________________
> notmuch mailing list
> notmuch at notmuchmail.org
> http://notmuchmail.org/mailman/listinfo/notmuch