From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: 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.