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

[Andrei POPESCU]

On Jo, 15 mar 12, 17:11:08, Austin Clements wrote:
> 
> I think having two divergent documents covering the same thing is less
> than ideal, but perhaps they could be merged in the near future.

I want to have this page more or less complete and descriptive. Once 
this is done I should be able to rewrite it more like a reference.

Regarding 'notmuch help search-terms':

$ notmuch help search-terms | wc -l
88

IMHO that text is better suited for a manpage, the help should be just a 
(very short) reference to refresh ones memory. What do you think?
 
> 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.

Then I think it's safe to assume the results are very much dependent on 
the language, so if the language has some similarities to English Xapian 
might do some stemming.

> Notmuch doesn't use synonyms.

Thanks.

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

Yes.

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

Not sure what you mean here. Does Xapian just ignore the '-' and 
searches as if it wasn't specified? I'm usually testing stuff with 
'notmuch count', but I get:

$ notmuch count -Debian
Unrecognized option: -Debian

With 'search' I get results, but right now I can't think of a query to 
test.

> "notmuch search term1 -term2" will work.

Does 'notmuch search -term1 term2' 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.

Right, anything other than brackets and '*'?

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

In such case I think it's better to state so.

I'll integrate all your comments (if somebody else doesn't beat me to 
it).

Kind regards,
Andrei
-- 
If you can't explain it simply, you don't understand it well enough.
(Albert Einstein)
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 490 bytes
Desc: Digital signature
URL: <http://notmuchmail.org/pipermail/notmuch/attachments/20120316/17ce32f2/attachment.pgp>