[RFC] http://notmuchmail.org/searching/ [was: Re: Improving notmuch query documentation]

[Austin Clements]

Quoth Andrei POPESCU on Mar 15 at 11:39 am:
> On Ma, 17 ian 12, 17:29:23, Austin Clements wrote:
> > Quoth Andrei Popescu on Jan 18 at 12:14 am:
> > > 
> > > If I get around to write something myself where do you suggest I should 
> > > start, the wiki or the manpage?
> > 
> > Probably expanding man/man7/notmuch-search-terms.7 would be the way to
> > go.
> 
> I went against your advice and created a new wiki page[1]. It is 
> currently not linked from anywhere on purpose, but IMVHO it would be 
> nice to have it linked from the home page.
> 
> [1] http://notmuchmail.org/searching/
> 
> Before that I would appreciate comments, corrections, etc. and 
> especially something to put in the 'Synonyms' section.

I think having two divergent documents covering the same thing is less
than ideal, but perhaps they could be merged in the near future.

A few comments:

The section on "Languages other than English" isn't quite correct.
Xapian has no idea what language is being used, so it will still stem
terms in other languages, but using English stemming rules.

Notmuch doesn't use synonyms.

It might be worth pointing out that "+term1" and "term1" are
equivalent.

"notmuch search -term2" doesn't actually work.  I've never looked in
to why, but I've found that Xapian ignores '-' at the beginning of a
query or a parenthesized expression.  "notmuch search term1 -term2"
will work.

In the brackets section, you'll need shell escaping for those queries
to work.  It might be worth pointing out the need for shell escaping
at the beginning.

XOR, NEAR, and ADJ were intentionally undocumented in
notmuch-search-terms because they may go away some day and we don't
want people thinking they can depend on them.