[PATCH 3/3] doc: add more information on operators.

[Jani Nikula]

On Sun, 18 Jan 2015, David Bremner <david at tethera.net> wrote:
> More material borrowed from the wiki page on "searching"
> ---
>  doc/man7/notmuch-search-terms.rst | 43 ++++++++++++++++++++++++++++++++++-----
>  1 file changed, 38 insertions(+), 5 deletions(-)
>
> diff --git a/doc/man7/notmuch-search-terms.rst b/doc/man7/notmuch-search-terms.rst
> index 3b27053..a315fbe 100644
> --- a/doc/man7/notmuch-search-terms.rst
> +++ b/doc/man7/notmuch-search-terms.rst
> @@ -118,17 +118,50 @@ The time range can also be specified using timestamps with a syntax of:
>  Each timestamp is a number representing the number of seconds since
>  1970-01-01 00:00:00 UTC.
>  
> -In addition to individual terms, multiple terms can be combined with
> -Boolean operators ( **and**, **or**, **not** , etc.). Each term in the
> -query will be implicitly connected by a logical AND if no explicit
> -operator is provided, (except that terms with a common prefix will be
> -implicitly combined with OR until we get Xapian defect #402 fixed).
> +Operators
> +---------
>  
> +In addition to individual terms, multiple terms can be combined with
> +Boolean operators ( **and**, **or**, **not**, and **xor**). Each term

Extra space after (.

> +in the query will be implicitly connected by a logical AND if no
> +explicit operator is provided, (except that terms with a common prefix
> +will be implicitly combined with OR until we get Xapian defect #402
> +fixed).  The shorthand '-<term>' can be used for 'not <term>' but
> +unfortunately this does not work at the start of an expression.

I think people expect tag:inbox tag:unread to have implicit OR by now,
so we could just drop the reference to the xapian defect.

Otherwise these patches LGTM, and I like getting this info into the man
page rather than the wiki.

BR,
Jani.



>  Parentheses can also be used to control the combination of the Boolean
>  operators, but will have to be protected from interpretation by the
>  shell, (such as by putting quotation marks around any parenthesized
>  expression).
>  
> +In addition to the standard boolean operators, Xapian provides several
> +operators specific to text searching.
> +
> +::
> +
> +        notmuch search term1 NEAR term2
> +
> +will return results where term1 is within 10 words of term2. The
> +threshold can be set like this:
> +
> +::
> +
> +        notmuch search term1 NEAR/2 term2
> +
> +The search
> +
> +::
> +
> +        notmuch search term1 ADJ term2
> +
> +will return results where term1 is within 10 words of term2, but in the
> +same order as in the query. The threshold can be set the same as with
> +NEAR:
> +
> +::
> +
> +        notmuch search term1 ADJ/7 term2
> +
> +
>  Stemming
>  --------
>  
> -- 
> 2.1.4