Date: Sat, 17 Mar 2012 00:29:52 +0200
From: Andrei POPESCU <andreimpopescu@gmail.com>
To: Austin Clements <amdragon@MIT.EDU>, David Bremner <david@tethera.net>
Subject: Re: [RFC] http://notmuchmail.org/searching/ [was: Re: Improving
	notmuch query documentation]
Message-ID: <20120316222952.GA4510@sid.nuvreauspam>
MIME-Version: 1.0
Content-Type: multipart/signed; micalg=pgp-sha256;
	protocol="application/pgp-signature"; boundary="xHFwDpU9dbj6ez1V"
Content-Disposition: inline
In-Reply-To: <87r4wso5d8.fsf@convex-new.cs.unb.ca>
	<20120316021124.GD2670@mit.edu>
User-Agent: Mutt/1.5.21 (2010-09-15)
Cc: notmuch@notmuchmail.org
Precedence: list


--xHFwDpU9dbj6ez1V
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

On Jo, 15 mar 12, 22:11:24, Austin Clements wrote:
> Quoth Andrei POPESCU on Mar 16 at  2:30 am:
> >=20
> > $ notmuch help search-terms | wc -l
> > 88
> >=20
> > IMHO that text is better suited for a manpage, the help should be just =
a=20
> > (very short) reference to refresh ones memory. What do you think?
>=20
> 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:
>=20
> 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=20
there should be very good reasons to have it longer than 20 lines or so.=20
Instead it's the entire section 'SEARCH SYNTAX' from the manpage.

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.

As I see it, the manpage (specifically section 'SEARCH SYNTAX' needs to=20
be expanded somewhat and 'help search-terms' shortened (a lot).

Does this make sense?

Kind regards,
Andrei
--=20
If you can't explain it simply, you don't understand it well enough.
(Albert Einstein)

--xHFwDpU9dbj6ez1V
Content-Type: application/pgp-signature; name="signature.asc"
Content-Description: Digital signature

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.12 (GNU/Linux)

iQEcBAEBCAAGBQJPY77gAAoJEHNWs3jeoi3pHeEIAJXTx2q7Hi04Amibtq2VaRqS
J6fDpTUVab8YJ3Ou8HFVDxN4KreCo+tOC9AD0ravVo/6qSzXG1U4vAmRNLbWkVRL
yrY3BTrGOBUrFwMSsj3X2yY7BrCzkWp0vL/JcnnN/5D2wo5gUv7OU/B5k7vDlh4S
G+YcwNy1KoGZaCPaFn1eDjYER9P0yzbyCFQMxc4ZlZbtfJBaY/UQU8F9/HaDXkX4
+lwVOUVdkiX1JJedXevrI/NmlWer8QAeoptLavxTvWOaa/TrsuyRfppPPR3+Gexj
eLmbSdM6fOy+lytumG7EakQ87m6+Q7vn6PerCcCmhPlxZ44ZQRdN43Jlz6V4EkQ=
=0rRx
-----END PGP SIGNATURE-----

--xHFwDpU9dbj6ez1V--