[Patch v3 10/15] man: update man pages for folder: and path: search terms

[Austin Clements]

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:

[Patch v3 10/15] man: update man pages for folder: and path: search terms

[David Bremner]

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:

+   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.

 The
 .B date:
-- 
1.8.5.3

[Patch v3 10/15] man: update man pages for folder: and path: search terms

[David Bremner]

From: Jani Nikula j...@nikula.org

---
 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:directory-path
 
+   path:directory-path or path:directory-path/**
+
date:since..until
 
 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.
 
 The
 .B date:
-- 
1.8.5.3

___
notmuch mailing list
notmuch@notmuchmail.org
http://notmuchmail.org/mailman/listinfo/notmuch

Re: [Patch v3 10/15] man: update man pages for folder: and path: search terms

[Austin Clements]

Quoth David Bremner on Mar 08 at  5:19 pm:
 From: Jani Nikula j...@nikula.org
 
 ---
  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:directory-path

Maybe change to folder:maildir-folder?

  
 + path:directory-path or path:directory-path/**
 +
   date:since..until
  
  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:
___
notmuch mailing list
notmuch@notmuchmail.org
http://notmuchmail.org/mailman/listinfo/notmuch