[RFC] http://notmuchmail.org/searching/ [was: Re: Improving notmuch query documentation]
andreimpopescu at gmail.com
Sat Mar 17 07:40:08 PDT 2012
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.
> 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
> > 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?
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