a4/caf1141fb2b1a01d9e94e4861fdefc0b24a441

   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 17EB3431FBD\r
   6         for <notmuch@notmuchmail.org>; Sat,  8 Mar 2014 19:52:52 -0800 (PST)\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 XvRuHFzq7+py for <notmuch@notmuchmail.org>;\r
  16         Sat,  8 Mar 2014 19:52:44 -0800 (PST)\r
  17 Received: from dmz-mailsec-scanner-2.mit.edu (dmz-mailsec-scanner-2.mit.edu\r
  18         [18.9.25.13])\r
  19         (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits))\r
  20         (No client certificate requested)\r
  21         by olra.theworths.org (Postfix) with ESMTPS id 94B0C431FB6\r
  22         for <notmuch@notmuchmail.org>; Sat,  8 Mar 2014 19:52:44 -0800 (PST)\r
  23 X-AuditID: 1209190d-f79776d000000ce9-8d-531be58a4ae4\r
  24 Received: from mailhub-auth-2.mit.edu ( [18.7.62.36])\r
  25         (using TLS with cipher AES256-SHA (256/256 bits))\r
  26         (Client did not present a certificate)\r
  27         by dmz-mailsec-scanner-2.mit.edu (Symantec Messaging Gateway) with SMTP\r
  28         id 7D.BE.03305.A85EB135; Sat,  8 Mar 2014 22:52:42 -0500 (EST)\r
  29 Received: from outgoing.mit.edu (outgoing-auth-1.mit.edu [18.9.28.11])\r
  30         by mailhub-auth-2.mit.edu (8.13.8/8.9.2) with ESMTP id s293qeHt011007; \r
  31         Sat, 8 Mar 2014 22:52:41 -0500\r
  32 Received: from awakening.csail.mit.edu (awakening.csail.mit.edu [18.26.4.91])\r
  33         (authenticated bits=0)\r
  34         (User authenticated as amdragon@ATHENA.MIT.EDU)\r
  35         by outgoing.mit.edu (8.13.8/8.12.4) with ESMTP id s293qdst009916\r
  36         (version=TLSv1/SSLv3 cipher=DHE-RSA-AES128-SHA bits=128 verify=NOT);\r
  37         Sat, 8 Mar 2014 22:52:40 -0500\r
  38 Received: from amthrax by awakening.csail.mit.edu with local (Exim 4.80)\r
  39         (envelope-from <amdragon@mit.edu>)\r
  40         id 1WMUn0-000302-Q1; Sat, 08 Mar 2014 22:52:38 -0500\r
  41 Date: Sat, 8 Mar 2014 22:52:38 -0500\r
  42 From: Austin Clements <amdragon@MIT.EDU>\r
  43 To: jani@nikula.org, David Bremner <david@tethera.net>\r
  44 Subject: Re: [Patch v3 10/15] man: update man pages for folder: and path:\r
  45         search terms\r
  46 Message-ID: <20140309035238.GN4709@mit.edu>\r
  47 References: <1394313585-28422-1-git-send-email-david@tethera.net>\r
  48         <1394313585-28422-11-git-send-email-david@tethera.net>\r
  49 MIME-Version: 1.0\r
  50 Content-Type: text/plain; charset=us-ascii\r
  51 Content-Disposition: inline\r
  52 In-Reply-To: <1394313585-28422-11-git-send-email-david@tethera.net>\r
  53 User-Agent: Mutt/1.5.21 (2010-09-15)\r
  54 X-Brightmail-Tracker:\r
  55  H4sIAAAAAAAAA+NgFuphleLIzCtJLcpLzFFi42IRYrdT0e16Kh1s0LNZyOJGazejRdN0Z4vr\r
  56         N2cyOzB73Lr/mt3j2apbzB5bDr1nDmCO4rJJSc3JLEst0rdL4MroP/ORueCYbMWc+yeYGxj/\r
  57         iHcxcnJICJhIbD51jBXCFpO4cG89WxcjF4eQwGwmiQv/JrFDOBsYJbbNuMIK4Zxiknh/8zdU\r
  58         ZgmjxMx/O1lA+lkEVCR+HTnEDGKzCWhIbNu/nLGLkYNDRMBMYtryWpAws4C0xLffzUwgtrBA\r
  59         hMTxed/ZQWxeAW2J9ZNng8WFBKokFu1fwgYRF5Q4OfMJC0SvlsSNfy+ZQEaCzFn+jwMkzCng\r
  60         LDHxzi+wraJAF0w5uY1tAqPQLCTds5B0z0LoXsDIvIpRNiW3Sjc3MTOnODVZtzg5MS8vtUjX\r
  61         SC83s0QvNaV0EyMo0DkleXcwvjuodIhRgINRiYe3Y4J0sBBrYllxZe4hRkkOJiVR3hMPgEJ8\r
  62         SfkplRmJxRnxRaU5qcWHGCU4mJVEeF92AuV4UxIrq1KL8mFS0hwsSuK8fWclgoUE0hNLUrNT\r
  63         UwtSi2CyMhwcShK8bMCIFhIsSk1PrUjLzClBSDNxcIIM5wEafvYJyPDigsTc4sx0iPwpRkUp\r
  64         cd5nIAkBkERGaR5cLywRvWIUB3pFmPcDSBUPMInBdb8CGswENLj5uBTI4JJEhJRUA+OJcJOX\r
  65         f56oT3Z/udV38/eSolnfrjlU9G52expzakFp5+T3vAHBEpFN38/1/286accwgS19+pz/XAHL\r
  66         /gWpnXnFFnhlhYZduPsjOZeAilSfY+73PpgW3XIwz3SOV1rPG7lJ9LXm1oBfMj+rpGy3rH99\r
  67         +JBuvrhKz6kfuz/KGfFsyT5eJjF1jagSS3FGoqEWc1FxIgCgTPqQHwMAAA==\r
  68 Cc: notmuch@notmuchmail.org\r
  69 X-BeenThere: notmuch@notmuchmail.org\r
  70 X-Mailman-Version: 2.1.13\r
  71 Precedence: list\r
  72 List-Id: "Use and development of the notmuch mail system."\r
  73         <notmuch.notmuchmail.org>\r
  74 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
  75         <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
  76 List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
  77 List-Post: <mailto:notmuch@notmuchmail.org>\r
  78 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
  79 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
  80         <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
  81 X-List-Received-Date: Sun, 09 Mar 2014 03:52:52 -0000\r
  82 \r
  83 Quoth David Bremner on Mar 08 at  5:19 pm:\r
  84 > From: Jani Nikula <jani@nikula.org>\r
  85 > \r
  86 > ---\r
  87 >  man/man7/notmuch-search-terms.7 | 28 ++++++++++++++++++++++------\r
  88 >  1 file changed, 22 insertions(+), 6 deletions(-)\r
  89 > \r
  90 > diff --git a/man/man7/notmuch-search-terms.7 b/man/man7/notmuch-search-terms.7\r
  91 > index a768b63..907403d 100644\r
  92 > --- a/man/man7/notmuch-search-terms.7\r
  93 > +++ b/man/man7/notmuch-search-terms.7\r
  94 > @@ -54,6 +54,8 @@ terms to match against specific portions of an email, (where\r
  95 >  \r
  96 >       folder:<directory-path>\r
  97 \r
  98 Maybe change to folder:<maildir-folder>?\r
  99 \r
 100 >  \r
 101 > +     path:<directory-path> or path:<directory-path>/**\r
 102 > +\r
 103 >       date:<since>..<until>\r
 104 >  \r
 105 >  The\r
 106 > @@ -101,12 +103,26 @@ thread ID values can be seen in the first column of output from\r
 107 >  \r
 108 >  The\r
 109 >  .B folder:\r
 110 > -prefix can be used to search for email message files that are\r
 111 > -contained within particular directories within the mail store. If the\r
 112 > -same email message has multiple message files associated with it, it's\r
 113 > -sufficient for a match that at least one of the files is contained\r
 114 > -within a matching directory. Only the directory components below the\r
 115 > -top-level mail database path are available to be searched.\r
 116 > +and\r
 117 > +.B path:\r
 118 > +prefixes can be used to search for email message files that are\r
 119 > +contained within particular directories within the mail store. The\r
 120 > +directories are specified relative from the top-level mail database\r
 121 > +path, and thus only the directory components below that are available\r
 122 > +to be searched.\r
 123 > +\r
 124 > +The\r
 125 > +.B folder:\r
 126 > +prefix matches messages in the specified maildir folder, i.e. in the\r
 127 > +specified directory and its "new" and "cur" subdirectories. The\r
 128 > +.B path:\r
 129 > +prefix matches messages in the specified directory only, unless the\r
 130 > +"/**" suffix is used to denote the specified directory and all its\r
 131 > +subdirectories recursively. For both, the empty string "" matches the\r
 132 > +top level maildir folder or directory. If the same email message has\r
 133 > +multiple message files associated with it, it's sufficient for a match\r
 134 > +that at least one of the files is contained within a matching\r
 135 > +directory.\r
 136 \r
 137 This isn't bad, but I think it could be more from a user's perspective\r
 138 without losing the operational details.  What about something like the\r
 139 following?  This follows much of what the above says, but is\r
 140 structured somewhat differently and works in some examples.\r
 141 \r
 142 The\r
 143 .B path:\r
 144 prefix searches for email messages that are in particular directories\r
 145 within the mail store.  The directory must be specified relative to\r
 146 the top-level maildir (and without the leading slash).  By default,\r
 147 .B path:\r
 148 matches messages in the specified directory only.  The "/**" suffix\r
 149 can be used to match messages in the specified directory and all its\r
 150 subdirectories recursively.\r
 151 .B path:""\r
 152 matches messages in the root of the mail store and, likewise,\r
 153 .B path:**\r
 154 matches all messages.\r
 155 \r
 156 The\r
 157 .B folder:\r
 158 prefix searches for email messages by maildir or MH folder.  For\r
 159 MH-style folders, this is equivalent to \fBpath:\fR.  For maildir,\r
 160 this includes messages in the "new" and "cur" subdirectories.  The\r
 161 exact syntax for maildir folders depends on your mail configuration.\r
 162 For maildir++, \fBfolder:""\fR matches the inbox folder (which is the\r
 163 root in maildir++), other folder names always start with ".", and\r
 164 nested folders are separated by "."s, such as\r
 165 \fBfolder:.classes.topology\fR.  For "file system" maildir, the inbox\r
 166 is typically \fBfolder:INBOX\fR and nested folders are separated by\r
 167 slashes, such as \fBfolder:classes/topology\fR.\r
 168 \r
 169 Both\r
 170 .B path:\r
 171 and\r
 172 .B folder:\r
 173 will find a message if \fIany\fR copy of that message is in the\r
 174 specific directory/folder.\r
 175 \r
 176 >  \r
 177 >  The\r
 178 >  .B date:\r