version: set new version and release date

[notmuch] / man / man1 / notmuch-search.1

diff --git a/man/man1/notmuch-search.1 b/man/man1/notmuch-search.1
index 5c771fa6e8da8a1a952aad2665dc4133ab99641b..07f6051ced1ac984c5ea67048c785256e51ba0c3 100644 (file)
--- a/man/man1/notmuch-search.1
+++ b/man/man1/notmuch-search.1
@@ -1,4 +1,4 @@
-.TH NOTMUCH-SEARCH 1 2012-08-20 "Notmuch 0.14"
+.TH NOTMUCH-SEARCH 1 2013-07-28 "Notmuch 0.16"

 .SH NAME
 notmuch-search \- search for messages matching the given search terms
 .SH SYNOPSIS
 .SH NAME
 notmuch-search \- search for messages matching the given search terms
 .SH SYNOPSIS


@@ -25,9 +25,11 @@ Supported options for
 include
 .RS 4
 .TP 4
 include
 .RS 4
 .TP 4

-.BR \-\-format= ( json | sexp | text )
+.BR \-\-format= ( json | sexp | text | text0 )

 
 

-Presents the results in either JSON, S-Expressions or plain-text (default).
+Presents the results in either JSON, S-Expressions, newline character
+separated plain-text (default), or null character separated plain-text
+(compatible with \fBxargs\fR(1) -0 option where available).

 .RE
 
 .RS 4
 .RE
 
 .RS 4


@@ -57,32 +59,36 @@ the authors of the thread and the subject.
 .B threads
 
 Output the thread IDs of all threads with any message matching the
 .B threads
 
 Output the thread IDs of all threads with any message matching the

-search terms, either one per line (\-\-format=text) or as a JSON array
-(\-\-format=json) or an S-Expression list (\-\-format=sexp).
+search terms, either one per line (\-\-format=text), separated by null
+characters (\-\-format=text0), as a JSON array (\-\-format=json), or
+an S-Expression list (\-\-format=sexp).

 .RE
 .RS 4
 .TP 4
 .B messages
 
 Output the message IDs of all messages matching the search terms,
 .RE
 .RS 4
 .TP 4
 .B messages
 
 Output the message IDs of all messages matching the search terms,

-either one per line (\-\-format=text) or as a JSON array
-(\-\-format=json) or as an S-Expression list (\-\-format=sexp).
+either one per line (\-\-format=text), separated by null characters
+(\-\-format=text0), as a JSON array (\-\-format=json), or as an
+S-Expression list (\-\-format=sexp).

 .RE
 .RS 4
 .TP 4
 .B files
 
 Output the filenames of all messages matching the search terms, either
 .RE
 .RS 4
 .TP 4
 .B files
 
 Output the filenames of all messages matching the search terms, either

-one per line (\-\-format=text) or as a JSON array (\-\-format=json) or
-as an S-Expression list (\-\-format=sexp).
+one per line (\-\-format=text), separated by null characters
+(\-\-format=text0), as a JSON array (\-\-format=json), or as an
+S-Expression list (\-\-format=sexp).

 .RE
 .RS 4
 .TP 4
 .B tags
 
 Output all tags that appear on any message matching the search terms,
 .RE
 .RS 4
 .TP 4
 .B tags
 
 Output all tags that appear on any message matching the search terms,

-either one per line (\-\-format=text) or as a JSON array (\-\-format=json)
-or as an S-Expression list (\-\-format=sexp).
+either one per line (\-\-format=text), separated by null characters
+(\-\-format=text0), as a JSON array (\-\-format=json), or as an
+S-Expression list (\-\-format=sexp).

 .RE
 .RE
 
 .RE
 .RE
 


@@ -124,15 +130,32 @@ Limit the number of displayed results to N.
 
 .RS 4
 .TP 4
 
 .RS 4
 .TP 4

-.BR \-\-exclude=(true|false|flag)
+.BR \-\-exclude=(true|false|all|flag)
+
+A message is called "excluded" if it matches at least one tag in
+search.tag_exclude that does not appear explicitly in the search terms.
+This option specifies whether to omit excluded messages in the search
+process.
+
+The default value,
+.BR true ,
+prevents excluded messages from matching the search terms.
+
+.B all
+additionally prevents excluded messages from appearing in displayed
+results, in effect behaving as though the excluded messages do not exist.
+
+.B false
+allows excluded messages to match search terms and appear in displayed
+results. Excluded messages are still marked in the relevant outputs.

 
 

-Specify whether to omit messages matching search.tag_exclude from the
-search results (the default) or not. The extra option

 .B flag
 only has an effect when
 .B flag
 only has an effect when

-.B --output=summary
-In this case all matching threads are returned but the "match count"
-is the number of matching non-excluded messages in the thread.
+.BR --output=summary .
+The output is almost identical to
+.BR false ,
+but the "match count" is the number of matching non-excluded messages in the
+thread, rather than the number of matching messages.

 .RE
 
 .SH EXIT STATUS
 .RE
 
 .SH EXIT STATUS


@@ -149,7 +172,8 @@ The requested format version is too new.
 .SH SEE ALSO
 
 \fBnotmuch\fR(1), \fBnotmuch-config\fR(1), \fBnotmuch-count\fR(1),
 .SH SEE ALSO
 
 \fBnotmuch\fR(1), \fBnotmuch-config\fR(1), \fBnotmuch-count\fR(1),

-\fBnotmuch-dump\fR(1), \fBnotmuch-hooks\fR(5), \fBnotmuch-new\fR(1),
+\fBnotmuch-dump\fR(1), \fBnotmuch-hooks\fR(5),
+\fBnotmuch-insert\fR(1), \fBnotmuch-new\fR(1),

 \fBnotmuch-reply\fR(1), \fBnotmuch-restore\fR(1),
 \fBnotmuch-search-terms\fR(7), \fBnotmuch-show\fR(1),
 \fBnotmuch-tag\fR(1)
 \fBnotmuch-reply\fR(1), \fBnotmuch-restore\fR(1),
 \fBnotmuch-search-terms\fR(7), \fBnotmuch-show\fR(1),
 \fBnotmuch-tag\fR(1)