Date: Sat, 17 Mar 2012 16:40:08 +0200
From: Andrei POPESCU <andreimpopescu@gmail.com>
To: Austin Clements <amdragon@MIT.EDU>
Subject: Re: [RFC] http://notmuchmail.org/searching/ [was: Re: Improving
	notmuch query documentation]
Message-ID: <20120317144008.GB4510@sid.nuvreauspam>
References: <87r4wso5d8.fsf@convex-new.cs.unb.ca>
	<20120316021124.GD2670@mit.edu>
	<20120316222952.GA4510@sid.nuvreauspam>
	<20120317002017.GG2670@mit.edu>
MIME-Version: 1.0
Content-Type: multipart/signed; micalg=pgp-sha256;
	protocol="application/pgp-signature"; boundary="GID0FwUMdk1T2AWN"
Content-Disposition: inline
In-Reply-To: <20120317002017.GG2670@mit.edu>
User-Agent: Mutt/1.5.21 (2010-09-15)
Cc: notmuch@notmuchmail.org
Precedence: list


--GID0FwUMdk1T2AWN
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

On Vi, 16 mar 12, 20:20:17, Austin Clements wrote:
>=20
> It is, quite literally, the manpage.  notmuch execs man when you run
> notmuch help.

Aha.
=20
> 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=20
> > applications. The '--help' is seldom longer than a few lines and just=
=20
> > lists the available options and parameters (more like a refresher). The=
=20
> > manpage then explains them in more detail.
>=20
> 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=20
point.

> > As I see it, the manpage (specifically section 'SEARCH SYNTAX' needs to=
=20
> > be expanded somewhat and 'help search-terms' shortened (a lot).
>=20
> 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=20
section in the manpage? How about expanding that part just a bit and not=20
show the text that comes from the manpage?

Kind regards,
Andrei
--=20
If you can't explain it simply, you don't understand it well enough.
(Albert Einstein)

--GID0FwUMdk1T2AWN
Content-Type: application/pgp-signature; name="signature.asc"
Content-Description: Digital signature

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.12 (GNU/Linux)

iQEcBAEBCAAGBQJPZKJIAAoJEHNWs3jeoi3p654H/0OQezTzMtxDJlu4tPdw+KP1
SJXPsZqkMGZncPXhasrPpIMLRIUL4Jqn0F5CEbOusHKNFv9ZoMtMTrTXV1Gt1tIb
Hj8Jer7K6/mXc0u/vOa3p0iHwLwMSoueICzMwK2w4ZebOVvI1RfNqsMLmLl2ONzt
uSfPwxtiX1HoFAygIGp+cyZ0wflEbXGgwwoDQxDwTEk8HVPASLPS2QlYi5pJ8NZQ
FmuGys0Vl/lP31K+XMTUtHDOY/02oLllbZRPo5AFauFj4feshqbTi1KB6YODJ9dj
8VyohcKrD/E1REojydM6Js9hJrrMMLxss7yMjHNsI6qs1rOO+2sQFDkI3oMcrAw=
=0hY6
-----END PGP SIGNATURE-----

--GID0FwUMdk1T2AWN--