From 2f4ee012bdf810549be535b52007bb184b600956 Mon Sep 17 00:00:00 2001 From: Andrei POPESCU Date: Sat, 17 Mar 2012 00:29:52 +0200 Subject: [PATCH] Re: [RFC] http://notmuchmail.org/searching/ [was: Re: Improving notmuch query documentation] --- 0e/9bb0f21360ca1065f43e571f34f8e2c7b44ca4 | 138 ++++++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 0e/9bb0f21360ca1065f43e571f34f8e2c7b44ca4 diff --git a/0e/9bb0f21360ca1065f43e571f34f8e2c7b44ca4 b/0e/9bb0f21360ca1065f43e571f34f8e2c7b44ca4 new file mode 100644 index 000000000..c44df6556 --- /dev/null +++ b/0e/9bb0f21360ca1065f43e571f34f8e2c7b44ca4 @@ -0,0 +1,138 @@ +Return-Path: +X-Original-To: notmuch@notmuchmail.org +Delivered-To: notmuch@notmuchmail.org +Received: from localhost (localhost [127.0.0.1]) + by olra.theworths.org (Postfix) with ESMTP id 8D9B7431FAF + for ; Fri, 16 Mar 2012 15:30:00 -0700 (PDT) +X-Virus-Scanned: Debian amavisd-new at olra.theworths.org +X-Spam-Flag: NO +X-Spam-Score: -0.798 +X-Spam-Level: +X-Spam-Status: No, score=-0.798 tagged_above=-999 required=5 + tests=[DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, + FAKE_REPLY_C=0.001, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_LOW=-0.7] + autolearn=disabled +Received: from olra.theworths.org ([127.0.0.1]) + by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024) + with ESMTP id ATkBsrpkyCsm for ; + Fri, 16 Mar 2012 15:29:58 -0700 (PDT) +Received: from mail-wi0-f179.google.com (mail-wi0-f179.google.com + [209.85.212.179]) (using TLSv1 with cipher RC4-SHA (128/128 bits)) + (No client certificate requested) + by olra.theworths.org (Postfix) with ESMTPS id 539CB431FAE + for ; Fri, 16 Mar 2012 15:29:58 -0700 (PDT) +Received: by wibhn6 with SMTP id hn6so1212008wib.2 + for ; Fri, 16 Mar 2012 15:29:55 -0700 (PDT) +DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; + h=date:from:to:cc:subject:message-id:mime-version:content-type + :content-disposition:in-reply-to:user-agent; + bh=Q6/SBm0bUlgxQmez8TeE16jCQJUeN80HjUCfmY3YMGQ=; + b=c3R9G3P/6EyMVIGag9gMgR8MXA00cTLxxC5FgqZRi8uhO+95ti1cOC9UpTAyjDD3zT + SiYnusHaWqphsh2vwf32YK/RxKOlcI8pqxP9Wg6zrJIUl6VJ5RgiAiqRwkuqPUHxhHCp + UbZSqIcPZ6022GJFAOhXCKfYzCPyoWXWR3oG7+ilALF7+qRwpxHwcb3mQ8QFVHHreH0F + +6KsCa+CKpgWXwbPLqjT6nX376IEmSmefk6qW89Bu9eprTn7FH5GJpb0eeQvRRjXiSLM + pZIdJYEcdvpZME3o8ZBbNdJ4584fbfXLf+gS2jz3lARy4PlbLO4xgrqW20+jm34CK43V + /pZw== +Received: by 10.180.93.4 with SMTP id cq4mr1948907wib.21.1331936995808; + Fri, 16 Mar 2012 15:29:55 -0700 (PDT) +Received: from sid.nuvreauspam ([92.86.142.199]) + by mx.google.com with ESMTPS id ff2sm3576533wib.9.2012.03.16.15.29.53 + (version=TLSv1/SSLv3 cipher=OTHER); + Fri, 16 Mar 2012 15:29:54 -0700 (PDT) +Received: by sid.nuvreauspam (Postfix, from userid 1077) + id 64014C02EE; Sat, 17 Mar 2012 00:29:52 +0200 (EET) +Date: Sat, 17 Mar 2012 00:29:52 +0200 +From: Andrei POPESCU +To: Austin Clements , David Bremner +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 +X-BeenThere: notmuch@notmuchmail.org +X-Mailman-Version: 2.1.13 +Precedence: list +List-Id: "Use and development of the notmuch mail system." + +List-Unsubscribe: , + +List-Archive: +List-Post: +List-Help: +List-Subscribe: , + +X-List-Received-Date: Fri, 16 Mar 2012 22:30:00 -0000 + + +--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 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-- -- 2.26.2