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

[Andrei POPESCU <andreimpopescu@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 1873 bytes --]

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)

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 490 bytes --]