[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 <andreimpopescu at 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: <http://notmuchmail.org/pipermail/notmuch/attachments/20120317/e0bd7337/attachment.pgp>