Date: Fri, 16 Mar 2012 20:20:17 -0400
From: Austin Clements <amdragon@MIT.EDU>
To: Andrei POPESCU <andreimpopescu@gmail.com>
Subject: Re: [RFC] http://notmuchmail.org/searching/ [was: Re: Improving
	notmuch query documentation]
Message-ID: <20120317002017.GG2670@mit.edu>
References: <87r4wso5d8.fsf@convex-new.cs.unb.ca>
	<20120316021124.GD2670@mit.edu>
	<20120316222952.GA4510@sid.nuvreauspam>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20120316222952.GA4510@sid.nuvreauspam>
User-Agent: Mutt/1.5.21 (2010-09-15)
Cc: notmuch@notmuchmail.org
Precedence: list

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 <andreimpopescu@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.