[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: <http://notmuchmail.org/pipermail/notmuch/attachments/20120317/01d0a1b4/attachment-0001.pgp>