[PATCH v4 09/13] man: update man pages for folder: and path: search terms

[Jani Nikula]

Text from review by Austin Clements <amdragon at MIT.EDU>.
---
 man/man7/notmuch-search-terms.7 | 41 ++++++++++++++++++++++++++++++++++-------
 1 file changed, 34 insertions(+), 7 deletions(-)

diff --git a/man/man7/notmuch-search-terms.7 b/man/man7/notmuch-search-terms.7
index a768b630a4d1..a33c8d78c122 100644
--- a/man/man7/notmuch-search-terms.7
+++ b/man/man7/notmuch-search-terms.7
@@ -52,7 +52,9 @@ terms to match against specific portions of an email, (where
 
 	thread:<thread-id>
 
-	folder:<directory-path>
+	folder:<maildir-folder>
+
+	path:<directory-path> or path:<directory-path>/**
 
 	date:<since>..<until>
 
@@ -100,13 +102,38 @@ thread ID values can be seen in the first column of output from
 .B "notmuch search"
 
 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:
-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.
+will find a message if \fIany\fR copy of that message is in the
+specific directory/folder.
 
 The
 .B date:
-- 
1.9.0