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

[David Bremner]

On Sat, 17 Mar 2012 00:29:52 +0200, Andrei POPESCU andreimpope...@gmail.com 
wrote:
 On Jo, 15 mar 12, 22:11:24, Austin Clements wrote:

 As I see it, the manpage (specifically section 'SEARCH SYNTAX' needs to 
 be expanded somewhat and 'help search-terms' shortened (a lot).
 
 Does this make sense?
 

I don't see that happening in the near future since all notmuch help
does is call man. As Austin said, you're welcome to improve the man
pages, but making them diverge from the help would require a complete
rewrite of all of the help.

d
___
notmuch mailing list
notmuch@notmuchmail.org
http://notmuchmail.org/mailman/listinfo/notmuch

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

[Andrei POPESCU]

On Sb, 17 mar 12, 13:16:47, Austin Clements wrote:
> Quoth Andrei POPESCU on Mar 17 at  4:40 pm:
> > > > As I see it, the manpage (specifically section 'SEARCH SYNTAX' needs to 
> > > > be expanded somewhat and 'help search-terms' shortened (a lot).
> 
> I realized that I didn't have a 'SEARCH SYNTAX' section and went
> digging into notmuch's code history.  Are you running from git or
> 0.11?

0.11 (Debian unstable/backports), but I just saw 0.12~rc1 in 
experimental.

> We completely restructured and unified the documentation several
> months ago, but it looks like we did so just days after the 0.11
> freeze, which means there hasn't been a stable release with the new
> documentation yet (though one is imminent).

Guess I should be looking at git then.

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: 

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

[Andrei POPESCU]

On Vi, 16 mar 12, 20:20:17, Austin Clements wrote:
> 
> It is, quite literally, the manpage.  notmuch execs man when you run
> notmuch help.

Aha.

> This was an intentional change a few releases ago.  Previously, we did
> have separate manpages and internal help documentation and it didn't
> work very well since they were perpetually out of sync.  Hence the
> general concern about documentation fragmentation.

Of course, I understand.

> > This opinion is based also on what I see around at other terminal 
> > applications. The '--help' is seldom longer than a few lines and just 
> > lists the available options and parameters (more like a refresher). The 
> > manpage then explains them in more detail.
> 
> That's true of simple commands, but most commands with subcommands
> follow a style like notmuch.  In fact, notmuch's approach was modeled
> directly off of git, and most modern VCSs do similar things.

'git help' and 'man git' are quite different on my system, but I get the 
point.

> > As I see it, the manpage (specifically section 'SEARCH SYNTAX' needs to 
> > be expanded somewhat and 'help search-terms' shortened (a lot).
> 
> What did you think of my suggestion that the first thing in man
> search-terms be a short reference so that's what you see immediately
> when you run notmuch help search-terms?  That seems to accomplish what
> you want without fragmenting the documentation and seems like a good
> way to write the documentation anyway.

I still have a question: where does the first part of
'notmuch help search-terms' come from? I can't find the corresponding 
section in the manpage? How about expanding that part just a bit and not 
show the text that comes from the manpage?

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: 

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

[Austin Clements]

Quoth Andrei POPESCU on Mar 17 at  4:40 pm:
> > > As I see it, the manpage (specifically section 'SEARCH SYNTAX' needs to 
> > > be expanded somewhat and 'help search-terms' shortened (a lot).

I realized that I didn't have a 'SEARCH SYNTAX' section and went
digging into notmuch's code history.  Are you running from git or
0.11?

We completely restructured and unified the documentation several
months ago, but it looks like we did so just days after the 0.11
freeze, which means there hasn't been a stable release with the new
documentation yet (though one is imminent).

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

[Andrei POPESCU]

On Jo, 15 mar 12, 22:11:24, Austin Clements wrote:
> Quoth Andrei POPESCU on Mar 16 at  2:30 am:
> > 
> > $ 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?
> 
> I'm not quite sure what you mean.  That text is the man page.  Though
> it sounds like a great idea to have a quick syntax reference at the
> top of the manpage so it's the first thing people see when they run
> 'notmuch help search-terms' (and they can still scroll down to get the
> details if they want).

On Vi, 16 mar 12, 13:52:35, David Bremner wrote:
> On Fri, 16 Mar 2012 02:30:53 +0200, Andrei POPESCU  gmail.com> wrote:
> 
> I'm less worried about the length of the documentation than about
> fragmentation. So I think if something is reference material, it should
> go in the man pages, or at least ship with notmuch.

What I mean is that 'notmuch help search-terms' is too verbose. IMHO 
there should be very good reasons to have it longer than 20 lines or so. 
Instead it's the entire section 'SEARCH SYNTAX' from the manpage.

This opinion is based also on what I see around at other terminal 
applications. The '--help' is seldom longer than a few lines and just 
lists the available options and parameters (more like a refresher). The 
manpage then explains them in more detail.

As I see it, the manpage (specifically section 'SEARCH SYNTAX' needs to 
be expanded somewhat and 'help search-terms' shortened (a lot).

Does this make sense?

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: 

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

[Andrei POPESCU]

On Vi, 16 mar 12, 20:20:17, Austin Clements wrote:
 
 It is, quite literally, the manpage.  notmuch execs man when you run
 notmuch help.

Aha.
 
 This was an intentional change a few releases ago.  Previously, we did
 have separate manpages and internal help documentation and it didn't
 work very well since they were perpetually out of sync.  Hence the
 general concern about documentation fragmentation.

Of course, I understand.

  This opinion is based also on what I see around at other terminal 
  applications. The '--help' is seldom longer than a few lines and just 
  lists the available options and parameters (more like a refresher). The 
  manpage then explains them in more detail.
 
 That's true of simple commands, but most commands with subcommands
 follow a style like notmuch.  In fact, notmuch's approach was modeled
 directly off of git, and most modern VCSs do similar things.

'git help' and 'man git' are quite different on my system, but I get the 
point.

  As I see it, the manpage (specifically section 'SEARCH SYNTAX' needs to 
  be expanded somewhat and 'help search-terms' shortened (a lot).
 
 What did you think of my suggestion that the first thing in man
 search-terms be a short reference so that's what you see immediately
 when you run notmuch help search-terms?  That seems to accomplish what
 you want without fragmenting the documentation and seems like a good
 way to write the documentation anyway.

I still have a question: where does the first part of
'notmuch help search-terms' come from? I can't find the corresponding 
section in the manpage? How about expanding that part just a bit and not 
show the text that comes from the manpage?

Kind regards,
Andrei
-- 
If you can't explain it simply, you don't understand it well enough.
(Albert Einstein)


signature.asc
Description: Digital signature
___
notmuch mailing list
notmuch@notmuchmail.org
http://notmuchmail.org/mailman/listinfo/notmuch

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

[Austin Clements]

Quoth Andrei POPESCU on Mar 17 at  4:40 pm:
   As I see it, the manpage (specifically section 'SEARCH SYNTAX' needs to 
   be expanded somewhat and 'help search-terms' shortened (a lot).

I realized that I didn't have a 'SEARCH SYNTAX' section and went
digging into notmuch's code history.  Are you running from git or
0.11?

We completely restructured and unified the documentation several
months ago, but it looks like we did so just days after the 0.11
freeze, which means there hasn't been a stable release with the new
documentation yet (though one is imminent).
___
notmuch mailing list
notmuch@notmuchmail.org
http://notmuchmail.org/mailman/listinfo/notmuch

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

[Andrei POPESCU]

On Sb, 17 mar 12, 13:16:47, Austin Clements wrote:
 Quoth Andrei POPESCU on Mar 17 at  4:40 pm:
As I see it, the manpage (specifically section 'SEARCH SYNTAX' needs to 
be expanded somewhat and 'help search-terms' shortened (a lot).
 
 I realized that I didn't have a 'SEARCH SYNTAX' section and went
 digging into notmuch's code history.  Are you running from git or
 0.11?

0.11 (Debian unstable/backports), but I just saw 0.12~rc1 in 
experimental.
 
 We completely restructured and unified the documentation several
 months ago, but it looks like we did so just days after the 0.11
 freeze, which means there hasn't been a stable release with the new
 documentation yet (though one is imminent).

Guess I should be looking at git then.

Kind regards,
Andrei
-- 
If you can't explain it simply, you don't understand it well enough.
(Albert Einstein)


signature.asc
Description: Digital signature
___
notmuch mailing list
notmuch@notmuchmail.org
http://notmuchmail.org/mailman/listinfo/notmuch

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

[Austin Clements]

Quoth Andrei POPESCU on Mar 17 at 12:29 am:
> On Jo, 15 mar 12, 22:11:24, Austin Clements wrote:
> > Quoth Andrei POPESCU on Mar 16 at  2:30 am:
> > > 
> > > $ 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?
> > 
> > I'm not quite sure what you mean.  That text is the man page.  Though
> > it sounds like a great idea to have a quick syntax reference at the
> > top of the manpage so it's the first thing people see when they run
> > 'notmuch help search-terms' (and they can still scroll down to get the
> > details if they want).
> 
> On Vi, 16 mar 12, 13:52:35, David Bremner wrote:
> > On Fri, 16 Mar 2012 02:30:53 +0200, Andrei POPESCU  > gmail.com> wrote:
> > 
> > I'm less worried about the length of the documentation than about
> > fragmentation. So I think if something is reference material, it should
> > go in the man pages, or at least ship with notmuch.
> 
> What I mean is that 'notmuch help search-terms' is too verbose. IMHO 
> there should be very good reasons to have it longer than 20 lines or so. 
> Instead it's the entire section 'SEARCH SYNTAX' from the manpage.

It is, quite literally, the manpage.  notmuch execs man when you run
notmuch help.

This was an intentional change a few releases ago.  Previously, we did
have separate manpages and internal help documentation and it didn't
work very well since they were perpetually out of sync.  Hence the
general concern about documentation fragmentation.

> This opinion is based also on what I see around at other terminal 
> applications. The '--help' is seldom longer than a few lines and just 
> lists the available options and parameters (more like a refresher). The 
> manpage then explains them in more detail.

That's true of simple commands, but most commands with subcommands
follow a style like notmuch.  In fact, notmuch's approach was modeled
directly off of git, and most modern VCSs do similar things.

> As I see it, the manpage (specifically section 'SEARCH SYNTAX' needs to 
> be expanded somewhat and 'help search-terms' shortened (a lot).

What did you think of my suggestion that the first thing in man
search-terms be a short reference so that's what you see immediately
when you run notmuch help search-terms?  That seems to accomplish what
you want without fragmenting the documentation and seems like a good
way to write the documentation anyway.

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

[David Bremner]

On Sat, 17 Mar 2012 00:29:52 +0200, Andrei POPESCU  wrote:
> On Jo, 15 mar 12, 22:11:24, Austin Clements wrote:

> As I see it, the manpage (specifically section 'SEARCH SYNTAX' needs to 
> be expanded somewhat and 'help search-terms' shortened (a lot).
> 
> Does this make sense?
> 

I don't see that happening in the near future since all notmuch help
does is call man. As Austin said, you're welcome to improve the man
pages, but making them diverge from the help would require a complete
rewrite of all of the help.

d

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

[David Bremner]

On Fri, 16 Mar 2012 02:30:53 +0200, Andrei POPESCU  wrote:

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

I'm less worried about the length of the documentation than about
fragmentation. So I think if something is reference material, it should
go in the man pages, or at least ship with notmuch.

d

[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: 

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

[David Bremner]

On Fri, 16 Mar 2012 02:30:53 +0200, Andrei POPESCU andreimpope...@gmail.com 
wrote:

 
 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?
  

I'm less worried about the length of the documentation than about
fragmentation. So I think if something is reference material, it should
go in the man pages, or at least ship with notmuch.

d
___
notmuch mailing list
notmuch@notmuchmail.org
http://notmuchmail.org/mailman/listinfo/notmuch

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

[Andrei POPESCU]

On Jo, 15 mar 12, 22:11:24, Austin Clements wrote:
 Quoth Andrei POPESCU on Mar 16 at  2:30 am:
  
  $ 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?
 
 I'm not quite sure what you mean.  That text is the man page.  Though
 it sounds like a great idea to have a quick syntax reference at the
 top of the manpage so it's the first thing people see when they run
 'notmuch help search-terms' (and they can still scroll down to get the
 details if they want).

On Vi, 16 mar 12, 13:52:35, David Bremner wrote:
 On Fri, 16 Mar 2012 02:30:53 +0200, Andrei POPESCU andreimpope...@gmail.com 
 wrote:
 
 I'm less worried about the length of the documentation than about
 fragmentation. So I think if something is reference material, it should
 go in the man pages, or at least ship with notmuch.

What I mean is that 'notmuch help search-terms' is too verbose. IMHO 
there should be very good reasons to have it longer than 20 lines or so. 
Instead it's the entire section 'SEARCH SYNTAX' from the manpage.

This opinion is based also on what I see around at other terminal 
applications. The '--help' is seldom longer than a few lines and just 
lists the available options and parameters (more like a refresher). The 
manpage then explains them in more detail.

As I see it, the manpage (specifically section 'SEARCH SYNTAX' needs to 
be expanded somewhat and 'help search-terms' shortened (a lot).

Does this make sense?

Kind regards,
Andrei
-- 
If you can't explain it simply, you don't understand it well enough.
(Albert Einstein)


signature.asc
Description: Digital signature
___
notmuch mailing list
notmuch@notmuchmail.org
http://notmuchmail.org/mailman/listinfo/notmuch

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

[Austin Clements]

Quoth Andrei POPESCU on Mar 17 at 12:29 am:
 On Jo, 15 mar 12, 22:11:24, Austin Clements wrote:
  Quoth Andrei POPESCU on Mar 16 at  2:30 am:
   
   $ 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?
  
  I'm not quite sure what you mean.  That text is the man page.  Though
  it sounds like a great idea to have a quick syntax reference at the
  top of the manpage so it's the first thing people see when they run
  'notmuch help search-terms' (and they can still scroll down to get the
  details if they want).
 
 On Vi, 16 mar 12, 13:52:35, David Bremner wrote:
  On Fri, 16 Mar 2012 02:30:53 +0200, Andrei POPESCU 
  andreimpope...@gmail.com wrote:
  
  I'm less worried about the length of the documentation than about
  fragmentation. So I think if something is reference material, it should
  go in the man pages, or at least ship with notmuch.
 
 What I mean is that 'notmuch help search-terms' is too verbose. IMHO 
 there should be very good reasons to have it longer than 20 lines or so. 
 Instead it's the entire section 'SEARCH SYNTAX' from the manpage.

It is, quite literally, the manpage.  notmuch execs man when you run
notmuch help.

This was an intentional change a few releases ago.  Previously, we did
have separate manpages and internal help documentation and it didn't
work very well since they were perpetually out of sync.  Hence the
general concern about documentation fragmentation.

 This opinion is based also on what I see around at other terminal 
 applications. The '--help' is seldom longer than a few lines and just 
 lists the available options and parameters (more like a refresher). The 
 manpage then explains them in more detail.

That's true of simple commands, but most commands with subcommands
follow a style like notmuch.  In fact, notmuch's approach was modeled
directly off of git, and most modern VCSs do similar things.

 As I see it, the manpage (specifically section 'SEARCH SYNTAX' needs to 
 be expanded somewhat and 'help search-terms' shortened (a lot).

What did you think of my suggestion that the first thing in man
search-terms be a short reference so that's what you see immediately
when you run notmuch help search-terms?  That seems to accomplish what
you want without fragmenting the documentation and seems like a good
way to write the documentation anyway.
___
notmuch mailing list
notmuch@notmuchmail.org
http://notmuchmail.org/mailman/listinfo/notmuch

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

[Austin Clements]

Quoth Andrei POPESCU on Mar 16 at  2:30 am:
> 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?

I'm not quite sure what you mean.  That text is the man page.  Though
it sounds like a great idea to have a quick syntax reference at the
top of the manpage so it's the first thing people see when they run
'notmuch help search-terms' (and they can still scroll down to get the
details if they want).

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

My point is that Xapian *will* do stemming, but using English stemming
rules, whether or not the language is English.  Hence it's inaccurate
to say that text in other languages will be unstemmed.  (Also, to be
fair to Xapian, it has stemmers for a whole bunch of languages; it's
notmuch that always configures it for English.)

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

I looked at this again and realized I was slightly wrong, so I had a
discussion with Olly and dug more in the code.  At a high level, a
query is a bunch of "probs" combined with boolean operators and the
actual rule is that a prob consisting solely of a single '-' term is a
syntax error.  And if a query has a syntax error, Xapian will re-parse
the entire query without any flags (which means no boolean operators,
love/hate, phrases, or wildcards).

One upshot of this rule is that a standalone negation like
'-tag:inbox' will actually search for messages *with* tag:inbox (just
like searching for 'tag:inbox'):

$ notmuch count -- -tag:inbox
650
$ notmuch count -- tag:inbox
650
$ notmuch count -- -tag:inbox x
9905

> 'notmuch count', but I get:
> 
> $ notmuch count -Debian
> Unrecognized option: -Debian

You need to tell count that it's not an option.  The standard getopt
syntax for this works:
  notmuch count -- -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?

'notmuch search -- -term1 term2' works.

> > 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 '*'?

Also double quotes.  E.g.,
  notmuch search subject:"This may look like a phrase, but don't be fooled"
will search for messages with "this" in the subject and the words
"may", "look", "like", etc anywhere (and in any order).

I think that's it for Xapian metacharacters, but of course things in
the query terms themselves could need shell escaping.  Rather than try
to think about this, I generally put my whole query in single quotes
unless it's something obviously trivial that won't contain any shell
metacharacters.

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

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

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

[Andrei POPESCU]

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.

Thanks,
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: 

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

[Andrei POPESCU]

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.

Thanks,
Andrei
-- 
If you can't explain it simply, you don't understand it well enough.
(Albert Einstein)


signature.asc
Description: Digital signature
___
notmuch mailing list
notmuch@notmuchmail.org
http://notmuchmail.org/mailman/listinfo/notmuch

Re: [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.
___
notmuch mailing list
notmuch@notmuchmail.org
http://notmuchmail.org/mailman/listinfo/notmuch

Re: [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)


signature.asc
Description: Digital signature
___
notmuch mailing list
notmuch@notmuchmail.org
http://notmuchmail.org/mailman/listinfo/notmuch

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

[Austin Clements]

Quoth Andrei POPESCU on Mar 16 at  2:30 am:
 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?

I'm not quite sure what you mean.  That text is the man page.  Though
it sounds like a great idea to have a quick syntax reference at the
top of the manpage so it's the first thing people see when they run
'notmuch help search-terms' (and they can still scroll down to get the
details if they want).

  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.

My point is that Xapian *will* do stemming, but using English stemming
rules, whether or not the language is English.  Hence it's inaccurate
to say that text in other languages will be unstemmed.  (Also, to be
fair to Xapian, it has stemmers for a whole bunch of languages; it's
notmuch that always configures it for English.)

  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 

I looked at this again and realized I was slightly wrong, so I had a
discussion with Olly and dug more in the code.  At a high level, a
query is a bunch of probs combined with boolean operators and the
actual rule is that a prob consisting solely of a single '-' term is a
syntax error.  And if a query has a syntax error, Xapian will re-parse
the entire query without any flags (which means no boolean operators,
love/hate, phrases, or wildcards).

One upshot of this rule is that a standalone negation like
'-tag:inbox' will actually search for messages *with* tag:inbox (just
like searching for 'tag:inbox'):

$ notmuch count -- -tag:inbox
650
$ notmuch count -- tag:inbox
650
$ notmuch count -- -tag:inbox x
9905

 'notmuch count', but I get:
 
 $ notmuch count -Debian
 Unrecognized option: -Debian

You need to tell count that it's not an option.  The standard getopt
syntax for this works:
  notmuch count -- -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?

'notmuch search -- -term1 term2' works.

  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 '*'?

Also double quotes.  E.g.,
  notmuch search subject:This may look like a phrase, but don't be fooled
will search for messages with this in the subject and the words
may, look, like, etc anywhere (and in any order).

I think that's it for Xapian metacharacters, but of course things in
the query terms themselves could need shell escaping.  Rather than try
to think about this, I generally put my whole query in single quotes
unless it's something obviously trivial that won't contain any shell
metacharacters.

  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
___
notmuch mailing list
notmuch@notmuchmail.org
http://notmuchmail.org/mailman/listinfo/notmuch