03/dfefaaa438e1bec0d2b9a275f1e59d109e6c08

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