From 7ababaf0303aa30e0613c4437139826bc26fa36d Mon Sep 17 00:00:00 2001 From: Austin Clements Date: Sat, 17 Mar 2012 20:20:17 +2000 Subject: [PATCH] Re: [RFC] http://notmuchmail.org/searching/ [was: Re: Improving notmuch query documentation] --- 03/dfefaaa438e1bec0d2b9a275f1e59d109e6c08 | 131 ++++++++++++++++++++++ 1 file changed, 131 insertions(+) create mode 100644 03/dfefaaa438e1bec0d2b9a275f1e59d109e6c08 diff --git a/03/dfefaaa438e1bec0d2b9a275f1e59d109e6c08 b/03/dfefaaa438e1bec0d2b9a275f1e59d109e6c08 new file mode 100644 index 000000000..ed4d7e9ef --- /dev/null +++ b/03/dfefaaa438e1bec0d2b9a275f1e59d109e6c08 @@ -0,0 +1,131 @@ +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 5ED1D431FAF + for ; Fri, 16 Mar 2012 17:20:22 -0700 (PDT) +X-Virus-Scanned: Debian amavisd-new at olra.theworths.org +X-Spam-Flag: NO +X-Spam-Score: -0.7 +X-Spam-Level: +X-Spam-Status: No, score=-0.7 tagged_above=-999 required=5 + tests=[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 s1W2TVDjviOH for ; + Fri, 16 Mar 2012 17:20:21 -0700 (PDT) +Received: from dmz-mailsec-scanner-7.mit.edu (DMZ-MAILSEC-SCANNER-7.MIT.EDU + [18.7.68.36]) + by olra.theworths.org (Postfix) with ESMTP id B181D431FAE + for ; Fri, 16 Mar 2012 17:20:21 -0700 (PDT) +X-AuditID: 12074424-b7fae6d000000906-44-4f63d8c43833 +Received: from mailhub-auth-4.mit.edu ( [18.7.62.39]) + by dmz-mailsec-scanner-7.mit.edu (Symantec Messaging Gateway) with SMTP + id 0C.CE.02310.4C8D36F4; Fri, 16 Mar 2012 20:20:20 -0400 (EDT) +Received: from outgoing.mit.edu (OUTGOING-AUTH.MIT.EDU [18.7.22.103]) + by mailhub-auth-4.mit.edu (8.13.8/8.9.2) with ESMTP id q2H0KJjO020181; + Fri, 16 Mar 2012 20:20:20 -0400 +Received: from awakening.csail.mit.edu (awakening.csail.mit.edu [18.26.4.91]) + (authenticated bits=0) + (User authenticated as amdragon@ATHENA.MIT.EDU) + by outgoing.mit.edu (8.13.6/8.12.4) with ESMTP id q2H0KHc5012700 + (version=TLSv1/SSLv3 cipher=AES256-SHA bits=256 verify=NOT); + Fri, 16 Mar 2012 20:20:18 -0400 (EDT) +Received: from amthrax by awakening.csail.mit.edu with local (Exim 4.77) + (envelope-from ) + id 1S8hNZ-0001PO-Kh; Fri, 16 Mar 2012 20:20:17 -0400 +Date: Fri, 16 Mar 2012 20:20:17 -0400 +From: Austin Clements +To: Andrei POPESCU +Subject: Re: [RFC] http://notmuchmail.org/searching/ [was: Re: Improving + notmuch query documentation] +Message-ID: <20120317002017.GG2670@mit.edu> +References: <87r4wso5d8.fsf@convex-new.cs.unb.ca> + <20120316021124.GD2670@mit.edu> + <20120316222952.GA4510@sid.nuvreauspam> +MIME-Version: 1.0 +Content-Type: text/plain; charset=us-ascii +Content-Disposition: inline +In-Reply-To: <20120316222952.GA4510@sid.nuvreauspam> +User-Agent: Mutt/1.5.21 (2010-09-15) +X-Brightmail-Tracker: + H4sIAAAAAAAAA+NgFupmleLIzCtJLcpLzFFi42IRYrdT1z1yI9nf4Pknc4tVE6QtbrR2M1pc + vzmT2YHZY+esu+wez1bdYvbYcug9cwBzFJdNSmpOZllqkb5dAlfGir/P2Qs6RCom7W9gbmB8 + wd/FyMkhIWAisah7LhuELSZx4d56IJuLQ0hgH6PE4451UM4GRok5c3axQzgnmSRmH/0G5Sxh + lJh6/gRjFyMHB4uAqsT16ZIgo9gENCS27V/OCGKLCOhKdL46wARiMwvYSRz53gUWFxZIl3i2 + YRqYzSugLXFpzSdWkDFCArUSS1qhwoISJ2c+YYFo1ZK48e8lE0gJs4C0xPJ/HCBhTqAHOpe+ + ZQexRQVUJKac3MY2gVFoFpLuWUi6ZyF0L2BkXsUom5JbpZubmJlTnJqsW5ycmJeXWqRrrpeb + WaKXmlK6iREc5i4qOxibDykdYhTgYFTi4eWYkOwvxJpYVlyZe4hRkoNJSZT3wWWgEF9Sfkpl + RmJxRnxRaU5q8SFGCQ5mJRHe99eBcrwpiZVVqUX5MClpDhYlcV4NrXd+QgLpiSWp2ampBalF + MFkZDg4lCd57II2CRanpqRVpmTklCGkmDk6Q4TxAw9lvgAwvLkjMLc5Mh8ifYlSUEuf9DdIs + AJLIKM2D64WloVeM4kCvCPNeBaniAaYwuO5XQIOZgAbPLAMbXJKIkJJqYJy3RmFRXXvu1zNG + T2sami+eWH4jLfn89nMmxYoXt3laS7vtb9Q7dHf1oQsBdpxLPJTTynh3f5owTYeLIcE6p0Bo + 9en6fVvX3uw2E5l3S2LzJLnujXP8j5yOXcXQzxS6SO/OzIwfrwtbFdsl23++EpyiLm8nnHxV + ZFmvp0de96/INZ9Xs2XFfVBiKc5INNRiLipOBADdinctHgMAAA== +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 00:20:22 -0000 + +Quoth Andrei POPESCU on Mar 17 at 12:29 am: +> On Jo, 15 mar 12, 22:11:24, Austin Clements wrote: +> > Quoth Andrei POPESCU on Mar 16 at 2:30 am: +> > > +> > > $ notmuch help search-terms | wc -l +> > > 88 +> > > +> > > IMHO that text is better suited for a manpage, the help should be just a +> > > (very short) reference to refresh ones memory. What do you think? +> > +> > 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: +> > +> > 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 +> there should be very good reasons to have it longer than 20 lines or so. +> Instead it's the entire section 'SEARCH SYNTAX' from the manpage. + +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. + +> 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. + +> 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. -- 2.26.2