From 0c75bd14ead5e6aa28b912a58b17aa9bb2c3d254 Mon Sep 17 00:00:00 2001 From: Andrei POPESCU Date: Sat, 17 Mar 2012 16:40:08 +0200 Subject: [PATCH] Re: [RFC] http://notmuchmail.org/searching/ [was: Re: Improving notmuch query documentation] --- a4/90260144ce4e29b5f40bde31278bbfab853b3b | 145 ++++++++++++++++++++++ 1 file changed, 145 insertions(+) create mode 100644 a4/90260144ce4e29b5f40bde31278bbfab853b3b diff --git a/a4/90260144ce4e29b5f40bde31278bbfab853b3b b/a4/90260144ce4e29b5f40bde31278bbfab853b3b new file mode 100644 index 000000000..dd9ded765 --- /dev/null +++ b/a4/90260144ce4e29b5f40bde31278bbfab853b3b @@ -0,0 +1,145 @@ +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 5451F431FAF + for ; Sat, 17 Mar 2012 07:40:16 -0700 (PDT) +X-Virus-Scanned: Debian amavisd-new at olra.theworths.org +X-Spam-Flag: NO +X-Spam-Score: -0.799 +X-Spam-Level: +X-Spam-Status: No, score=-0.799 tagged_above=-999 required=5 + tests=[DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, + 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 Hohky6EWYbZO for ; + Sat, 17 Mar 2012 07:40:14 -0700 (PDT) +Received: from mail-we0-f181.google.com (mail-we0-f181.google.com + [74.125.82.181]) (using TLSv1 with cipher RC4-SHA (128/128 bits)) + (No client certificate requested) + by olra.theworths.org (Postfix) with ESMTPS id A23FE431FAE + for ; Sat, 17 Mar 2012 07:40:14 -0700 (PDT) +Received: by werm13 with SMTP id m13so5360088wer.26 + for ; Sat, 17 Mar 2012 07:40:11 -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:references:mime-version + :content-type:content-disposition:in-reply-to:user-agent; + bh=fohZB1uMO4t6IVzzU+5sFxidMca8TrMqnlJoSqJgaEY=; + b=ZAK/q6Es49nn8nHfyxxtGuBmywFNFTJW+qUyaT8P1at/KvJR/eLS2diOjWrMQ7ocwo + WQGWb/e7r4OVZDMsbWP7ScCt62gWhrfWQeTPIbZ7kI2E8XwwO171Uw4+dPbScZ5um7k/ + y3RE97sVQ7Jx2YlAJdIxa9A6VrbUdrTReCl0SGizkjbyj4Jx4wqEyXPzPi9OBtVmpA2H + WyjMSVwpcGZEI3sSCpB/HeljqasPQmlUf2OiFBtdiz8qK18+3yotO5T+3BNPT0KngnVN + 4dNfv7E6cD0o3k/YroFrk1hVRk0ApA773WRdfBWtoxGuLhahoE1L8h224uC3yisbrHQ5 + HY5g== +Received: by 10.180.83.72 with SMTP id o8mr6704336wiy.5.1331995211918; + Sat, 17 Mar 2012 07:40:11 -0700 (PDT) +Received: from sid.nuvreauspam ([92.86.142.199]) + by mx.google.com with ESMTPS id l5sm8193961wia.11.2012.03.17.07.40.09 + (version=TLSv1/SSLv3 cipher=OTHER); + Sat, 17 Mar 2012 07:40:10 -0700 (PDT) +Received: by sid.nuvreauspam (Postfix, from userid 1077) + id B8F69C05C4; Sat, 17 Mar 2012 16:40:08 +0200 (EET) +Date: Sat, 17 Mar 2012 16:40:08 +0200 +From: Andrei POPESCU +To: Austin Clements +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 +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: Sat, 17 Mar 2012 14:40:16 -0000 + + +--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-- -- 2.26.2