--- /dev/null
+Return-Path: <amdragon@mit.edu>\r
+X-Original-To: notmuch@notmuchmail.org\r
+Delivered-To: notmuch@notmuchmail.org\r
+Received: from localhost (localhost [127.0.0.1])\r
+ by olra.theworths.org (Postfix) with ESMTP id 5ED1D431FAF\r
+ for <notmuch@notmuchmail.org>; Fri, 16 Mar 2012 17:20:22 -0700 (PDT)\r
+X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
+X-Spam-Flag: NO\r
+X-Spam-Score: -0.7\r
+X-Spam-Level: \r
+X-Spam-Status: No, score=-0.7 tagged_above=-999 required=5\r
+ tests=[RCVD_IN_DNSWL_LOW=-0.7] autolearn=disabled\r
+Received: from olra.theworths.org ([127.0.0.1])\r
+ by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)\r
+ with ESMTP id s1W2TVDjviOH for <notmuch@notmuchmail.org>;\r
+ Fri, 16 Mar 2012 17:20:21 -0700 (PDT)\r
+Received: from dmz-mailsec-scanner-7.mit.edu (DMZ-MAILSEC-SCANNER-7.MIT.EDU\r
+ [18.7.68.36])\r
+ by olra.theworths.org (Postfix) with ESMTP id B181D431FAE\r
+ for <notmuch@notmuchmail.org>; Fri, 16 Mar 2012 17:20:21 -0700 (PDT)\r
+X-AuditID: 12074424-b7fae6d000000906-44-4f63d8c43833\r
+Received: from mailhub-auth-4.mit.edu ( [18.7.62.39])\r
+ by dmz-mailsec-scanner-7.mit.edu (Symantec Messaging Gateway) with SMTP\r
+ id 0C.CE.02310.4C8D36F4; Fri, 16 Mar 2012 20:20:20 -0400 (EDT)\r
+Received: from outgoing.mit.edu (OUTGOING-AUTH.MIT.EDU [18.7.22.103])\r
+ by mailhub-auth-4.mit.edu (8.13.8/8.9.2) with ESMTP id q2H0KJjO020181; \r
+ Fri, 16 Mar 2012 20:20:20 -0400\r
+Received: from awakening.csail.mit.edu (awakening.csail.mit.edu [18.26.4.91])\r
+ (authenticated bits=0)\r
+ (User authenticated as amdragon@ATHENA.MIT.EDU)\r
+ by outgoing.mit.edu (8.13.6/8.12.4) with ESMTP id q2H0KHc5012700\r
+ (version=TLSv1/SSLv3 cipher=AES256-SHA bits=256 verify=NOT);\r
+ Fri, 16 Mar 2012 20:20:18 -0400 (EDT)\r
+Received: from amthrax by awakening.csail.mit.edu with local (Exim 4.77)\r
+ (envelope-from <amdragon@MIT.EDU>)\r
+ id 1S8hNZ-0001PO-Kh; Fri, 16 Mar 2012 20:20:17 -0400\r
+Date: Fri, 16 Mar 2012 20:20:17 -0400\r
+From: Austin Clements <amdragon@MIT.EDU>\r
+To: Andrei POPESCU <andreimpopescu@gmail.com>\r
+Subject: Re: [RFC] http://notmuchmail.org/searching/ [was: Re: Improving\r
+ notmuch query documentation]\r
+Message-ID: <20120317002017.GG2670@mit.edu>\r
+References: <87r4wso5d8.fsf@convex-new.cs.unb.ca>\r
+ <20120316021124.GD2670@mit.edu>\r
+ <20120316222952.GA4510@sid.nuvreauspam>\r
+MIME-Version: 1.0\r
+Content-Type: text/plain; charset=us-ascii\r
+Content-Disposition: inline\r
+In-Reply-To: <20120316222952.GA4510@sid.nuvreauspam>\r
+User-Agent: Mutt/1.5.21 (2010-09-15)\r
+X-Brightmail-Tracker:\r
+ H4sIAAAAAAAAA+NgFupmleLIzCtJLcpLzFFi42IRYrdT1z1yI9nf4Pknc4tVE6QtbrR2M1pc\r
+ vzmT2YHZY+esu+wez1bdYvbYcug9cwBzFJdNSmpOZllqkb5dAlfGir/P2Qs6RCom7W9gbmB8\r
+ wd/FyMkhIWAisah7LhuELSZx4d56IJuLQ0hgH6PE4451UM4GRok5c3axQzgnmSRmH/0G5Sxh\r
+ lJh6/gRjFyMHB4uAqsT16ZIgo9gENCS27V/OCGKLCOhKdL46wARiMwvYSRz53gUWFxZIl3i2\r
+ YRqYzSugLXFpzSdWkDFCArUSS1qhwoISJ2c+YYFo1ZK48e8lE0gJs4C0xPJ/HCBhTqAHOpe+\r
+ ZQexRQVUJKac3MY2gVFoFpLuWUi6ZyF0L2BkXsUom5JbpZubmJlTnJqsW5ycmJeXWqRrrpeb\r
+ WaKXmlK6iREc5i4qOxibDykdYhTgYFTi4eWYkOwvxJpYVlyZe4hRkoNJSZT3wWWgEF9Sfkpl\r
+ RmJxRnxRaU5q8SFGCQ5mJRHe99eBcrwpiZVVqUX5MClpDhYlcV4NrXd+QgLpiSWp2ampBalF\r
+ MFkZDg4lCd57II2CRanpqRVpmTklCGkmDk6Q4TxAw9lvgAwvLkjMLc5Mh8ifYlSUEuf9DdIs\r
+ AJLIKM2D64WloVeM4kCvCPNeBaniAaYwuO5XQIOZgAbPLAMbXJKIkJJqYJy3RmFRXXvu1zNG\r
+ T2sami+eWH4jLfn89nMmxYoXt3laS7vtb9Q7dHf1oQsBdpxLPJTTynh3f5owTYeLIcE6p0Bo\r
+ 9en6fVvX3uw2E5l3S2LzJLnujXP8j5yOXcXQzxS6SO/OzIwfrwtbFdsl23++EpyiLm8nnHxV\r
+ ZFmvp0de96/INZ9Xs2XFfVBiKc5INNRiLipOBADdinctHgMAAA==\r
+Cc: notmuch@notmuchmail.org\r
+X-BeenThere: notmuch@notmuchmail.org\r
+X-Mailman-Version: 2.1.13\r
+Precedence: list\r
+List-Id: "Use and development of the notmuch mail system."\r
+ <notmuch.notmuchmail.org>\r
+List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
+ <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
+List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
+List-Post: <mailto:notmuch@notmuchmail.org>\r
+List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
+List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
+ <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
+X-List-Received-Date: Sat, 17 Mar 2012 00:20:22 -0000\r
+\r
+Quoth Andrei POPESCU on Mar 17 at 12:29 am:\r
+> On Jo, 15 mar 12, 22:11:24, Austin Clements wrote:\r
+> > Quoth Andrei POPESCU on Mar 16 at 2:30 am:\r
+> > > \r
+> > > $ notmuch help search-terms | wc -l\r
+> > > 88\r
+> > > \r
+> > > IMHO that text is better suited for a manpage, the help should be just a \r
+> > > (very short) reference to refresh ones memory. What do you think?\r
+> > \r
+> > I'm not quite sure what you mean. That text is the man page. Though\r
+> > it sounds like a great idea to have a quick syntax reference at the\r
+> > top of the manpage so it's the first thing people see when they run\r
+> > 'notmuch help search-terms' (and they can still scroll down to get the\r
+> > details if they want).\r
+> \r
+> On Vi, 16 mar 12, 13:52:35, David Bremner wrote:\r
+> > On Fri, 16 Mar 2012 02:30:53 +0200, Andrei POPESCU <andreimpopescu@gmail.com> wrote:\r
+> > \r
+> > I'm less worried about the length of the documentation than about\r
+> > fragmentation. So I think if something is reference material, it should\r
+> > go in the man pages, or at least ship with notmuch.\r
+> \r
+> What I mean is that 'notmuch help search-terms' is too verbose. IMHO \r
+> there should be very good reasons to have it longer than 20 lines or so. \r
+> Instead it's the entire section 'SEARCH SYNTAX' from the manpage.\r
+\r
+It is, quite literally, the manpage. notmuch execs man when you run\r
+notmuch help.\r
+\r
+This was an intentional change a few releases ago. Previously, we did\r
+have separate manpages and internal help documentation and it didn't\r
+work very well since they were perpetually out of sync. Hence the\r
+general concern about documentation fragmentation.\r
+\r
+> This opinion is based also on what I see around at other terminal \r
+> applications. The '--help' is seldom longer than a few lines and just \r
+> lists the available options and parameters (more like a refresher). The \r
+> manpage then explains them in more detail.\r
+\r
+That's true of simple commands, but most commands with subcommands\r
+follow a style like notmuch. In fact, notmuch's approach was modeled\r
+directly off of git, and most modern VCSs do similar things.\r
+\r
+> As I see it, the manpage (specifically section 'SEARCH SYNTAX' needs to \r
+> be expanded somewhat and 'help search-terms' shortened (a lot).\r
+\r
+What did you think of my suggestion that the first thing in man\r
+search-terms be a short reference so that's what you see immediately\r
+when you run notmuch help search-terms? That seems to accomplish what\r
+you want without fragmenting the documentation and seems like a good\r
+way to write the documentation anyway.\r
projects / notmuch-archives.git / commitdiff