Return-Path: <bremner@tethera.net>
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 174E4429E41
	for <notmuch@notmuchmail.org>; Tue, 11 Mar 2014 16:02:31 -0700 (PDT)
X-Virus-Scanned: Debian amavisd-new at olra.theworths.org
X-Spam-Flag: NO
X-Spam-Score: 0
X-Spam-Level: 
X-Spam-Status: No, score=0 tagged_above=-999 required=5 tests=[none]
	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 JIpzjODNfTdU for <notmuch@notmuchmail.org>;
	Tue, 11 Mar 2014 16:02:27 -0700 (PDT)
Received: from yantan.tethera.net (yantan.tethera.net [199.188.72.155])
	(using TLSv1 with cipher DHE-RSA-AES128-SHA (128/128 bits))
	(No client certificate requested)
	by olra.theworths.org (Postfix) with ESMTPS id F11AF431FDC
	for <notmuch@notmuchmail.org>; Tue, 11 Mar 2014 16:02:17 -0700 (PDT)
Received: from remotemail by yantan.tethera.net with local (Exim 4.80)
	(envelope-from <bremner@tethera.net>)
	id 1WNVgf-0001vP-Fm; Tue, 11 Mar 2014 20:02:17 -0300
Received: (nullmailer pid 25865 invoked by uid 1000); Tue, 11 Mar 2014
	23:01:46 -0000
From: David Bremner <david@tethera.net>
To: notmuch@notmuchmail.org
Subject: [Patch v6 13/14] man: update man pages for folder: and path: search
	terms
Date: Tue, 11 Mar 2014 20:01:39 -0300
Message-Id: <1394578900-25618-14-git-send-email-david@tethera.net>
X-Mailer: git-send-email 1.8.5.3
In-Reply-To: <1394578900-25618-1-git-send-email-david@tethera.net>
References: <1394578900-25618-1-git-send-email-david@tethera.net>
X-BeenThere: notmuch@notmuchmail.org
X-Mailman-Version: 2.1.13
Precedence: list
List-Id: "Use and development of the notmuch mail system."
	<notmuch.notmuchmail.org>
List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,
	<mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>
List-Archive: <http://notmuchmail.org/pipermail/notmuch>
List-Post: <mailto:notmuch@notmuchmail.org>
List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>
List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,
	<mailto:notmuch-request@notmuchmail.org?subject=subscribe>
X-List-Received-Date: Tue, 11 Mar 2014 23:02:31 -0000

From: Jani Nikula <jani@nikula.org>

Text from review by Austin Clements <amdragon@MIT.EDU>.
---
 doc/man7/notmuch-search-terms.rst | 32 +++++++++++++++++++++++++-------
 1 file changed, 25 insertions(+), 7 deletions(-)

diff --git a/doc/man7/notmuch-search-terms.rst b/doc/man7/notmuch-search-terms.rst
index 20bc6f1..1acdaa0 100644
--- a/doc/man7/notmuch-search-terms.rst
+++ b/doc/man7/notmuch-search-terms.rst
@@ -46,7 +46,9 @@ indicate user-supplied values):
 
 -  thread:<thread-id>
 
--  folder:<directory-path>
+-  folder:<maildir-folder>
+
+-  path:<directory-path> or path:<directory-path>/**
 
 -  date:<since>..<until>
 
@@ -77,12 +79,28 @@ generated internally by notmuch (and do not appear in email messages).
 These thread ID values can be seen in the first column of output from
 **notmuch search**
 
-The **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.
+The **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, **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.
+**path:""** matches messages in the root of the mail store and,
+likewise, **path:\*\*** matches all messages.
+
+The **folder:** prefix searches for email messages by maildir or MH
+folder. For MH-style folders, this is equivalent to **path:**. For
+maildir, this includes messages in the "new" and "cur"
+subdirectories. The exact syntax for maildir folders depends on your
+mail configuration. For maildir++, **folder:""** 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
+**folder:.classes.topology**. For "file system" maildir, the inbox is
+typically **folder:INBOX** and nested folders are separated by
+slashes, such as **folder:classes/topology**.
+
+Both **path:** and **folder:** will find a message if *any* copy of
+that message is in the specific directory/folder.
 
 The **date:** prefix can be used to restrict the results to only
 messages within a particular time range (based on the Date: header) with
-- 
1.8.5.3