[RFC] http://notmuchmail.org/searching/ [was: Re: Improving notmuch query documentation]
andreimpopescu at gmail.com
Fri Mar 16 15:29:52 PDT 2012
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?
If you can't explain it simply, you don't understand it well enough.
-------------- next part --------------
A non-text attachment was scrubbed...
Size: 490 bytes
Desc: Digital signature
More information about the notmuch