From ae8d6489beb9e46c161db34926f544700228df2c Mon Sep 17 00:00:00 2001 From: Austin Clements Date: Sun, 9 Mar 2014 22:52:38 +1900 Subject: [PATCH] Re: [Patch v3 10/15] man: update man pages for folder: and path: search terms --- a4/caf1141fb2b1a01d9e94e4861fdefc0b24a441 | 178 ++++++++++++++++++++++ 1 file changed, 178 insertions(+) create mode 100644 a4/caf1141fb2b1a01d9e94e4861fdefc0b24a441 diff --git a/a4/caf1141fb2b1a01d9e94e4861fdefc0b24a441 b/a4/caf1141fb2b1a01d9e94e4861fdefc0b24a441 new file mode 100644 index 000000000..2c013740d --- /dev/null +++ b/a4/caf1141fb2b1a01d9e94e4861fdefc0b24a441 @@ -0,0 +1,178 @@ +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 17EB3431FBD + for ; Sat, 8 Mar 2014 19:52:52 -0800 (PST) +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 XvRuHFzq7+py for ; + Sat, 8 Mar 2014 19:52:44 -0800 (PST) +Received: from dmz-mailsec-scanner-2.mit.edu (dmz-mailsec-scanner-2.mit.edu + [18.9.25.13]) + (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) + (No client certificate requested) + by olra.theworths.org (Postfix) with ESMTPS id 94B0C431FB6 + for ; Sat, 8 Mar 2014 19:52:44 -0800 (PST) +X-AuditID: 1209190d-f79776d000000ce9-8d-531be58a4ae4 +Received: from mailhub-auth-2.mit.edu ( [18.7.62.36]) + (using TLS with cipher AES256-SHA (256/256 bits)) + (Client did not present a certificate) + by dmz-mailsec-scanner-2.mit.edu (Symantec Messaging Gateway) with SMTP + id 7D.BE.03305.A85EB135; Sat, 8 Mar 2014 22:52:42 -0500 (EST) +Received: from outgoing.mit.edu (outgoing-auth-1.mit.edu [18.9.28.11]) + by mailhub-auth-2.mit.edu (8.13.8/8.9.2) with ESMTP id s293qeHt011007; + Sat, 8 Mar 2014 22:52:41 -0500 +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.8/8.12.4) with ESMTP id s293qdst009916 + (version=TLSv1/SSLv3 cipher=DHE-RSA-AES128-SHA bits=128 verify=NOT); + Sat, 8 Mar 2014 22:52:40 -0500 +Received: from amthrax by awakening.csail.mit.edu with local (Exim 4.80) + (envelope-from ) + id 1WMUn0-000302-Q1; Sat, 08 Mar 2014 22:52:38 -0500 +Date: Sat, 8 Mar 2014 22:52:38 -0500 +From: Austin Clements +To: jani@nikula.org, David Bremner +Subject: Re: [Patch v3 10/15] man: update man pages for folder: and path: + search terms +Message-ID: <20140309035238.GN4709@mit.edu> +References: <1394313585-28422-1-git-send-email-david@tethera.net> + <1394313585-28422-11-git-send-email-david@tethera.net> +MIME-Version: 1.0 +Content-Type: text/plain; charset=us-ascii +Content-Disposition: inline +In-Reply-To: <1394313585-28422-11-git-send-email-david@tethera.net> +User-Agent: Mutt/1.5.21 (2010-09-15) +X-Brightmail-Tracker: + H4sIAAAAAAAAA+NgFuphleLIzCtJLcpLzFFi42IRYrdT0e16Kh1s0LNZyOJGazejRdN0Z4vr + N2cyOzB73Lr/mt3j2apbzB5bDr1nDmCO4rJJSc3JLEst0rdL4MroP/ORueCYbMWc+yeYGxj/ + iHcxcnJICJhIbD51jBXCFpO4cG89WxcjF4eQwGwmiQv/JrFDOBsYJbbNuMIK4Zxiknh/8zdU + ZgmjxMx/O1lA+lkEVCR+HTnEDGKzCWhIbNu/nLGLkYNDRMBMYtryWpAws4C0xLffzUwgtrBA + hMTxed/ZQWxeAW2J9ZNng8WFBKokFu1fwgYRF5Q4OfMJC0SvlsSNfy+ZQEaCzFn+jwMkzCng + LDHxzi+wraJAF0w5uY1tAqPQLCTds5B0z0LoXsDIvIpRNiW3Sjc3MTOnODVZtzg5MS8vtUjX + SC83s0QvNaV0EyMo0DkleXcwvjuodIhRgINRiYe3Y4J0sBBrYllxZe4hRkkOJiVR3hMPgEJ8 + SfkplRmJxRnxRaU5qcWHGCU4mJVEeF92AuV4UxIrq1KL8mFS0hwsSuK8fWclgoUE0hNLUrNT + UwtSi2CyMhwcShK8bMCIFhIsSk1PrUjLzClBSDNxcIIM5wEafvYJyPDigsTc4sx0iPwpRkUp + cd5nIAkBkERGaR5cLywRvWIUB3pFmPcDSBUPMInBdb8CGswENLj5uBTI4JJEhJRUA+OJcJOX + f56oT3Z/udV38/eSolnfrjlU9G52expzakFp5+T3vAHBEpFN38/1/286accwgS19+pz/XAHL + /gWpnXnFFnhlhYZduPsjOZeAilSfY+73PpgW3XIwz3SOV1rPG7lJ9LXm1oBfMj+rpGy3rH99 + +JBuvrhKz6kfuz/KGfFsyT5eJjF1jagSS3FGoqEWc1FxIgCgTPqQHwMAAA== +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: Sun, 09 Mar 2014 03:52:52 -0000 + +Quoth David Bremner on Mar 08 at 5:19 pm: +> From: Jani Nikula +> +> --- +> man/man7/notmuch-search-terms.7 | 28 ++++++++++++++++++++++------ +> 1 file changed, 22 insertions(+), 6 deletions(-) +> +> diff --git a/man/man7/notmuch-search-terms.7 b/man/man7/notmuch-search-terms.7 +> index a768b63..907403d 100644 +> --- a/man/man7/notmuch-search-terms.7 +> +++ b/man/man7/notmuch-search-terms.7 +> @@ -54,6 +54,8 @@ terms to match against specific portions of an email, (where +> +> folder: + +Maybe change to folder:? + +> +> + path: or path:/** +> + +> date:.. +> +> The +> @@ -101,12 +103,26 @@ thread ID values can be seen in the first column of output from +> +> The +> .B folder: +> -prefix can be used to search for email message files that are +> -contained within particular directories within the mail store. If the +> -same email message has multiple message files associated with it, it's +> -sufficient for a match that at least one of the files is contained +> -within a matching directory. Only the directory components below the +> -top-level mail database path are available to be searched. +> +and +> +.B path: +> +prefixes can be used to search for email message files that are +> +contained within particular directories within the mail store. The +> +directories are specified relative from the top-level mail database +> +path, and thus only the directory components below that are available +> +to be searched. +> + +> +The +> +.B folder: +> +prefix matches messages in the specified maildir folder, i.e. in the +> +specified directory and its "new" and "cur" subdirectories. The +> +.B path: +> +prefix matches messages in the specified directory only, unless the +> +"/**" suffix is used to denote the specified directory and all its +> +subdirectories recursively. For both, the empty string "" matches the +> +top level maildir folder or directory. If the same email message has +> +multiple message files associated with it, it's sufficient for a match +> +that at least one of the files is contained within a matching +> +directory. + +This isn't bad, but I think it could be more from a user's perspective +without losing the operational details. What about something like the +following? This follows much of what the above says, but is +structured somewhat differently and works in some examples. + +The +.B path: +prefix searches for email messages that are in particular directories +within the mail store. The directory must be specified relative to +the top-level maildir (and without the leading slash). By default, +.B path: +matches messages in the specified directory only. The "/**" suffix +can be used to match messages in the specified directory and all its +subdirectories recursively. +.B path:"" +matches messages in the root of the mail store and, likewise, +.B path:** +matches all messages. + +The +.B folder: +prefix searches for email messages by maildir or MH folder. For +MH-style folders, this is equivalent to \fBpath:\fR. For maildir, +this includes messages in the "new" and "cur" subdirectories. The +exact syntax for maildir folders depends on your mail configuration. +For maildir++, \fBfolder:""\fR matches the inbox folder (which is the +root in maildir++), other folder names always start with ".", and +nested folders are separated by "."s, such as +\fBfolder:.classes.topology\fR. For "file system" maildir, the inbox +is typically \fBfolder:INBOX\fR and nested folders are separated by +slashes, such as \fBfolder:classes/topology\fR. + +Both +.B path: +and +.B folder: +will find a message if \fIany\fR copy of that message is in the +specific directory/folder. + +> +> The +> .B date: -- 2.26.2