diff options
| author | Tomi Ollila <tomi.ollila@iki.fi> | 2013-01-19 19:15:09 +0200 |
|---|---|---|
| committer | Tomi Ollila <tomi.ollila@iki.fi> | 2013-01-19 19:15:09 +0200 |
| commit | 0b22ed1b4e640539ae8e6f78f1ea88e54426a50d (patch) | |
| tree | 51acd3ae19be660f636fa422096b766a33185cea | |
| parent | 525aa4f91e00109bcc331a6f6186848ae6ed7b1f (diff) | |
manpages 0.15
| -rw-r--r-- | manpages.mdwn | 2 | ||||
| -rw-r--r-- | manpages/notmuch-1.mdwn | 2 | ||||
| -rw-r--r-- | manpages/notmuch-config-1.mdwn | 2 | ||||
| -rw-r--r-- | manpages/notmuch-count-1.mdwn | 2 | ||||
| -rw-r--r-- | manpages/notmuch-dump-1.mdwn | 61 | ||||
| -rw-r--r-- | manpages/notmuch-hooks-5.mdwn | 2 | ||||
| -rw-r--r-- | manpages/notmuch-new-1.mdwn | 2 | ||||
| -rw-r--r-- | manpages/notmuch-reply-1.mdwn | 65 | ||||
| -rw-r--r-- | manpages/notmuch-restore-1.mdwn | 55 | ||||
| -rw-r--r-- | manpages/notmuch-search-1.mdwn | 80 | ||||
| -rw-r--r-- | manpages/notmuch-search-terms-7.mdwn | 149 | ||||
| -rw-r--r-- | manpages/notmuch-setup-1.mdwn | 2 | ||||
| -rw-r--r-- | manpages/notmuch-show-1.mdwn | 118 | ||||
| -rw-r--r-- | manpages/notmuch-tag-1.mdwn | 79 |
14 files changed, 463 insertions, 158 deletions
diff --git a/manpages.mdwn b/manpages.mdwn index 1953ff6..6bb01fa 100644 --- a/manpages.mdwn +++ b/manpages.mdwn @@ -14,5 +14,3 @@ Manual page index * <a href='notmuch-tag-1/'>notmuch-tag</a>(1) - add/remove tags for all messages matching the search terms * <a href='notmuch-hooks-5/'>notmuch-hooks</a>(5) - hooks for notmuch * <a href='notmuch-search-terms-7/'>notmuch-search-terms</a>(7) - syntax for notmuch queries - -<h2>Notmuch 0.14</h2> diff --git a/manpages/notmuch-1.mdwn b/manpages/notmuch-1.mdwn index 98d0d81..3e9ad06 100644 --- a/manpages/notmuch-1.mdwn +++ b/manpages/notmuch-1.mdwn @@ -119,4 +119,4 @@ (server: irc.freenode.net, channel: #notmuch). </pre> -<h2>Notmuch 0.14</h2> +<h2>Notmuch 0.15</h2> diff --git a/manpages/notmuch-config-1.mdwn b/manpages/notmuch-config-1.mdwn index e54a4f0..b9850cf 100644 --- a/manpages/notmuch-config-1.mdwn +++ b/manpages/notmuch-config-1.mdwn @@ -117,4 +117,4 @@ <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7), <a href='../notmuch-show-1/'>notmuch-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1) </pre> -<h2>Notmuch 0.14</h2> +<h2>Notmuch 0.15</h2> diff --git a/manpages/notmuch-count-1.mdwn b/manpages/notmuch-count-1.mdwn index b917808..9d9767f 100644 --- a/manpages/notmuch-count-1.mdwn +++ b/manpages/notmuch-count-1.mdwn @@ -48,4 +48,4 @@ <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7), <a href='../notmuch-show-1/'>notmuch-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1) </pre> -<h2>Notmuch 0.14</h2> +<h2>Notmuch 0.15</h2> diff --git a/manpages/notmuch-dump-1.mdwn b/manpages/notmuch-dump-1.mdwn index 92424b6..743be97 100644 --- a/manpages/notmuch-dump-1.mdwn +++ b/manpages/notmuch-dump-1.mdwn @@ -7,7 +7,8 @@ <h2>SYNOPSIS</h2> <pre> - <b>notmuch</b> <b>dump</b> [ --output=<<u>filename</u>> ] [--] [ <<u>search-term</u>>...] + <b>notmuch</b> <b>dump</b> [<b>--format=(sup|batch-tag)</b>] [--] [ --output=<<u>filename</u>> ] + [--] [ <<u>search-term</u>>...] </pre> <h2>DESCRIPTION</h2> @@ -16,24 +17,62 @@ Output is to the given filename, if any, or to stdout. - These tags are the only data in the notmuch database that can't be - recreated from the messages themselves. The output of notmuch dump is - therefore the only critical thing to backup (and much more friendly to + These tags are the only data in the notmuch database that can't be + recreated from the messages themselves. The output of notmuch dump is + therefore the only critical thing to backup (and much more friendly to incremental backup than the native database files.) - With no search terms, a dump of all messages in the database will be - generated. A "--" argument instructs notmuch that the remaining argu- - ments are search terms. + <b>--format=(sup|batch-tag)</b> - See <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7) for details of the supported syntax for - <search-terms>. + Notmuch restore supports two plain text dump formats, both with one + message-id per line, followed by a list of tags. + + <b>sup</b> The <b>sup</b> dump file format is specifically chosen to be compati- + ble with the format of files produced by sup-dump. So if + you've previously been using sup for mail, then the <b>notmuch</b> + <b>restore</b> command provides you a way to import all of your tags + (or labels as sup calls them). Each line has the following + form + + <<u>message-id</u>> <b>(</b> <<u>tag</u>> ... <b>)</b> + + with zero or more tags are separated by spaces. Note that (mal- + formed) message-ids may contain arbitrary non-null characters. + Note also that tags with spaces will not be correctly restored + with this format. + + <b>batch-tag</b> + + The <b>batch-tag</b> dump format is intended to more robust against + malformed message-ids and tags containing whitespace or non- + <b>ascii</b>(7) characters. Each line has the form + + +<<u>encoded-tag</u>> +<<u>encoded-tag</u>> ... -- id:<<u>quoted-message-id</u>> + + Tags are hex-encoded by replacing every byte not matching the + regex <b>[A-Za-z0-9@=.,</b>_<b>+-]</b> with <b>%nn</b> where nn is the two digit hex + encoding. The message ID is a valid Xapian query, quoted using + Xapian boolean term quoting rules: if the ID contains whites- + pace or a close paren or starts with a double quote, it must be + enclosed in double quotes and double quotes inside the ID must + be doubled. The astute reader will notice this is a special + case of the batch input format for <a href='../notmuch-tag-1/'>notmuch-tag</a>(1); note that + the single message-id query is mandatory for <a href='../notmuch-restore-1/'>notmuch-</a> + <a href='../notmuch-restore-1/'>restore</a>(1). + + With no search terms, a dump of all messages in the database will + be generated. A "--" argument instructs notmuch that the remaining + arguments are search terms. + + See <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7) for details of the supported syntax for + <search-terms>. </pre> <h2>SEE ALSO</h2> <pre> <a href='../notmuch-1/'>notmuch</a>(1), <a href='../notmuch-config-1/'>notmuch-config</a>(1), <a href='../notmuch-count-1/'>notmuch-count</a>(1), <a href='../notmuch-hooks-5/'>notmuch-hooks</a>(5), <a href='../notmuch-new-1/'>not-</a> - <a href='../notmuch-new-1/'>much-new</a>(1), <a href='../notmuch-reply-1/'>notmuch-reply</a>(1), <a href='../notmuch-restore-1/'>notmuch-restore</a>(1), <a href='../notmuch-search-1/'>notmuch-search</a>(1), + <a href='../notmuch-new-1/'>much-new</a>(1), <a href='../notmuch-reply-1/'>notmuch-reply</a>(1), <a href='../notmuch-restore-1/'>notmuch-restore</a>(1), <a href='../notmuch-search-1/'>notmuch-search</a>(1), <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7), <a href='../notmuch-show-1/'>notmuch-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1) </pre> -<h2>Notmuch 0.14</h2> +<h2>Notmuch 0.15</h2> diff --git a/manpages/notmuch-hooks-5.mdwn b/manpages/notmuch-hooks-5.mdwn index 207c29f..a813dfd 100644 --- a/manpages/notmuch-hooks-5.mdwn +++ b/manpages/notmuch-hooks-5.mdwn @@ -45,4 +45,4 @@ <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7), <a href='../notmuch-show-1/'>notmuch-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1) </pre> -<h2>Notmuch 0.14</h2> +<h2>Notmuch 0.15</h2> diff --git a/manpages/notmuch-new-1.mdwn b/manpages/notmuch-new-1.mdwn index 6977e21..fee5cea 100644 --- a/manpages/notmuch-new-1.mdwn +++ b/manpages/notmuch-new-1.mdwn @@ -50,4 +50,4 @@ <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7), <a href='../notmuch-show-1/'>notmuch-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1) </pre> -<h2>Notmuch 0.14</h2> +<h2>Notmuch 0.15</h2> diff --git a/manpages/notmuch-reply-1.mdwn b/manpages/notmuch-reply-1.mdwn index 9fe2795..0d9f8c2 100644 --- a/manpages/notmuch-reply-1.mdwn +++ b/manpages/notmuch-reply-1.mdwn @@ -34,7 +34,7 @@ Supported options for <b>reply</b> include - <b>--format=</b>(<b>default</b>|<b>json</b>|<b>headers-only</b>) + <b>--format=</b>(<b>default</b>|<b>json</b>|<b>sexp</b>|<b>headers-only</b>) <b>default</b> Includes subject and quoted message body. @@ -45,48 +45,69 @@ put can be used by a client to create a reply message intelligently. + <b>sexp</b> + Produces S-Expression output containing headers for a + reply message and the contents of the original message. + This output can be used by a client to create a reply + message intelligently. + <b>headers-only</b> - Only produces In-Reply-To, References, To, Cc, and Bcc + Only produces In-Reply-To, References, To, Cc, and Bcc headers. + <b>--format-version=N</b> + + Use the specified structured output format version. This is + intended for programs that invoke <a href='../notmuch-1/'>notmuch</a>(1) internally. If + omitted, the latest supported version will be used. + <b>--reply-to=</b>(<b>all</b>|<b>sender</b>) <b>all</b> (default) Replies to all addresses. <b>sender</b> - Replies only to the sender. If replying to user's own - message (Reply-to: or From: header is one of the user's - configured email addresses), try To:, Cc:, and Bcc: - headers in this order, and copy values from the first - that contains something other than only the user's + Replies only to the sender. If replying to user's own + message (Reply-to: or From: header is one of the user's + configured email addresses), try To:, Cc:, and Bcc: + headers in this order, and copy values from the first + that contains something other than only the user's addresses. <b>--decrypt</b> - Decrypt any MIME encrypted parts found in the selected - content (ie. "multipart/encrypted" parts). Status of the - decryption will be reported (currently only supported with - --format=json) and the multipart/encrypted part will be - replaced by the decrypted content. + Decrypt any MIME encrypted parts found in the selected con- + tent (ie. "multipart/encrypted" parts). Status of the + decryption will be reported (currently only supported with + --format=json and --format=sexp) and the multipart/encrypted + part will be replaced by the decrypted content. - See <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7) for details of the supported syntax for + See <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7) for details of the supported syntax for <search-terms>. - Note: It is most common to use <b>notmuch</b> <b>reply</b> with a search string - matching a single message, (such as id:<message-id>), but it can be + Note: It is most common to use <b>notmuch</b> <b>reply</b> with a search string + matching a single message, (such as id:<message-id>), but it can be useful to reply to several messages at once. For example, when a series - of patches are sent in a single thread, replying to the entire thread - allows for the reply to comment on issues found in multiple patches. - The default format supports replying to multiple messages at once, but - the JSON format does not. + of patches are sent in a single thread, replying to the entire thread + allows for the reply to comment on issues found in multiple patches. + The default format supports replying to multiple messages at once, but + the JSON and S-Expression formats do not. +</pre> + +<h2>EXIT STATUS</h2> +<pre> + This command supports the following special exit status codes + + <b>20</b> The requested format version is too old. + + <b>21</b> The requested format version is too new. </pre> <h2>SEE ALSO</h2> <pre> - <a href='../notmuch-1/'>notmuch</a>(1), <a href='../notmuch-config-1/'>notmuch-config</a>(1), <a href='../notmuch-count-1/'>notmuch-count</a>(1), <a href='../notmuch-dump-1/'>notmuch-dump</a>(1), <a href='../notmuch-hooks-5/'>not-</a> - <a href='../notmuch-hooks-5/'>much-hooks</a>(5), <a href='../notmuch-new-1/'>notmuch-new</a>(1), <a href='../notmuch-restore-1/'>notmuch-restore</a>(1), <a href='../notmuch-search-1/'>notmuch-search</a>(1), + <a href='../notmuch-1/'>notmuch</a>(1), <a href='../notmuch-config-1/'>notmuch-config</a>(1), <a href='../notmuch-count-1/'>notmuch-count</a>(1), <a href='../notmuch-dump-1/'>notmuch-dump</a>(1), <a href='../notmuch-hooks-5/'>not-</a> + <a href='../notmuch-hooks-5/'>much-hooks</a>(5), <a href='../notmuch-new-1/'>notmuch-new</a>(1), <a href='../notmuch-restore-1/'>notmuch-restore</a>(1), <a href='../notmuch-search-1/'>notmuch-search</a>(1), <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7), <a href='../notmuch-show-1/'>notmuch-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1) </pre> -<h2>Notmuch 0.14</h2> +<h2>Notmuch 0.15</h2> diff --git a/manpages/notmuch-restore-1.mdwn b/manpages/notmuch-restore-1.mdwn index 555ae6a..87869c9 100644 --- a/manpages/notmuch-restore-1.mdwn +++ b/manpages/notmuch-restore-1.mdwn @@ -8,7 +8,8 @@ <h2>SYNOPSIS</h2> <pre> - <b>notmuch</b> <b>restore</b> [<b>--accumulate</b>] [ --input=<<u>filename</u>> ] + <b>notmuch</b> <b>restore</b> [<b>--accumulate</b>] [<b>--format=(auto|batch-tag|sup)</b>] [ + --input=<<u>filename</u>> ] </pre> <h2>DESCRIPTION</h2> @@ -17,28 +18,50 @@ The input is read from the given filename, if any, or from stdin. - Note: The dump file format is specifically chosen to be compatible with - the format of files produced by sup-dump. So if you've previously been - using sup for mail, then the <b>notmuch</b> <b>restore</b> command provides you a way - to import all of your tags (or labels as sup calls them). + Supported options for <b>restore</b> include - The --accumulate switch causes the union of the existing and new tags - to be applied, instead of replacing each message's tags as they are - read in from the dump file. + <b>--accumulate</b> - See <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7) for details of the supported syntax for - <search-terms>. + The union of the existing and new tags is applied, instead of + replacing each message's tags as they are read in from the dump + file. - <b>notmuch</b> <b>restore</b> updates the maildir flags according to tag changes if - the <b>maildir.synchronize</b>_<b>flags</b> configuration option is enabled. See <a href='../notmuch-config-1/'>not-</a> - <a href='../notmuch-config-1/'>much-config</a>(1) for details. + <b>--format=(sup|batch-tag|auto)</b> + + Notmuch restore supports two plain text dump formats, with each + line specifying a message-id and a set of tags. For details of + the actual formats, see <a href='../notmuch-dump-1/'>notmuch-dump</a>(1). + + <b>sup</b> The <b>sup</b> dump file format is specifically chosen to be com- + patible with the format of files produced by sup-dump. So + if you've previously been using sup for mail, then the <b>not-</b> + <b>much</b> <b>restore</b> command provides you a way to import all of + your tags (or labels as sup calls them). + + <b>batch-tag</b> + + The <b>batch-tag</b> dump format is intended to more robust + against malformed message-ids and tags containing whites- + pace or non-<b>ascii</b>(7) characters. See <a href='../notmuch-dump-1/'>notmuch-dump</a>(1) for + details on this format. + + <b>notmuch</b> <b>restore</b> updates the maildir flags according to tag + changes if the <b>maildir.synchronize</b>_<b>flags</b> configuration + option is enabled. See <a href='../notmuch-config-1/'>notmuch-config</a>(1) for details. + + <b>auto</b> + + This option (the default) tries to guess the format from + the input. For correctly formed input in either supported + format, this heuristic, based the fact that batch-tag for- + mat contains no parentheses, should be accurate. </pre> <h2>SEE ALSO</h2> <pre> - <a href='../notmuch-1/'>notmuch</a>(1), <a href='../notmuch-config-1/'>notmuch-config</a>(1), <a href='../notmuch-count-1/'>notmuch-count</a>(1), <a href='../notmuch-dump-1/'>notmuch-dump</a>(1), <a href='../notmuch-hooks-5/'>not-</a> - <a href='../notmuch-hooks-5/'>much-hooks</a>(5), <a href='../notmuch-new-1/'>notmuch-new</a>(1), <a href='../notmuch-reply-1/'>notmuch-reply</a>(1), <a href='../notmuch-search-1/'>notmuch-search</a>(1), + <a href='../notmuch-1/'>notmuch</a>(1), <a href='../notmuch-config-1/'>notmuch-config</a>(1), <a href='../notmuch-count-1/'>notmuch-count</a>(1), <a href='../notmuch-dump-1/'>notmuch-dump</a>(1), <a href='../notmuch-hooks-5/'>not-</a> + <a href='../notmuch-hooks-5/'>much-hooks</a>(5), <a href='../notmuch-new-1/'>notmuch-new</a>(1), <a href='../notmuch-reply-1/'>notmuch-reply</a>(1), <a href='../notmuch-search-1/'>notmuch-search</a>(1), <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7), <a href='../notmuch-show-1/'>notmuch-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1) </pre> -<h2>Notmuch 0.14</h2> +<h2>Notmuch 0.15</h2> diff --git a/manpages/notmuch-search-1.mdwn b/manpages/notmuch-search-1.mdwn index b042815..5afb0f7 100644 --- a/manpages/notmuch-search-1.mdwn +++ b/manpages/notmuch-search-1.mdwn @@ -26,62 +26,77 @@ Supported options for <b>search</b> include - <b>--format=</b>(<b>json</b>|<b>text</b>) + <b>--format=</b>(<b>json</b>|<b>sexp</b>|<b>text</b>|<b>text0</b>) - Presents the results in either JSON 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 <b>xargs</b>(1) -0 option where + available). + + <b>--format-version=N</b> + + Use the specified structured output format version. This is + intended for programs that invoke <a href='../notmuch-1/'>notmuch</a>(1) internally. If + omitted, the latest supported version will be used. <b>--output=(summary|threads|messages|files|tags)</b> <b>summary</b> - Output a summary of each thread with any message matching + Output a summary of each thread with any message matching the search terms. The summary includes the thread ID, date, - the number of messages in the thread (both the number - matched and the total number), the authors of the thread + the number of messages in the thread (both the number + matched and the total number), the authors of the thread and the subject. <b>threads</b> - Output the thread IDs of all threads with any message - matching the search terms, either one per line (--for- - mat=text) or as a JSON array (--format=json). + Output the thread IDs of all threads with any message + matching the search terms, either one per line (--for- + mat=text), separated by null characters (--format=text0), + as a JSON array (--format=json), or an S-Expression list + (--format=sexp). <b>messages</b> - Output the message IDs of all messages matching the search - terms, either one per line (--format=text) or as a JSON - array (--format=json). + Output the message IDs of all messages matching the search + terms, either one per line (--format=text), separated by + null characters (--format=text0), as a JSON array (--for- + mat=json), or as an S-Expression list (--format=sexp). <b>files</b> Output the filenames of all messages matching the search - terms, either one per line (--format=text) or as a JSON - array (--format=json). + terms, either one per line (--format=text), separated by + null characters (--format=text0), as a JSON array (--for- + mat=json), or as an S-Expression list (--format=sexp). <b>tags</b> - 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). + Output all tags that appear on any message matching the + search terms, either one per line (--format=text), sepa- + rated by null characters (--format=text0), as a JSON array + (--format=json), or as an S-Expression list (--for- + mat=sexp). <b>--sort=</b>(<b>newest-first</b>|<b>oldest-first</b>) This option can be used to present results in either chronolog- - ical order (<b>oldest-first</b>) or reverse chronological order + ical order (<b>oldest-first</b>) or reverse chronological order (<b>newest-first</b>). - Note: The thread order will be distinct between these two - options (beyond being simply reversed). When sorting by <b>old-</b> - <b>est-first</b> the threads will be sorted by the oldest message in - each thread, but when sorting by <b>newest-first</b> the threads will + Note: The thread order will be distinct between these two + options (beyond being simply reversed). When sorting by <b>old-</b> + <b>est-first</b> the threads will be sorted by the oldest message in + each thread, but when sorting by <b>newest-first</b> the threads will be sorted by the newest message in each thread. - By default, results will be displayed in reverse chronological + By default, results will be displayed in reverse chronological order, (that is, the newest results will be displayed first). <b>--offset=[-]N</b> - Skip displaying the first N results. With the leading '-', + Skip displaying the first N results. With the leading '-', start at the Nth result from the end. <b>--limit=N</b> @@ -90,18 +105,27 @@ <b>--exclude=(true|false|flag)</b> - Specify whether to omit messages matching search.tag_exclude - from the search results (the default) or not. The extra option - <b>flag</b> only has an effect when <b>--output=summary</b> In this case all + Specify whether to omit messages matching search.tag_exclude + from the search results (the default) or not. The extra option + <b>flag</b> only has an effect when <b>--output=summary</b> In this case all matching threads are returned but the "match count" is the num- ber of matching non-excluded messages in the thread. </pre> +<h2>EXIT STATUS</h2> +<pre> + This command supports the following special exit status codes + + <b>20</b> The requested format version is too old. + + <b>21</b> The requested format version is too new. +</pre> + <h2>SEE ALSO</h2> <pre> - <a href='../notmuch-1/'>notmuch</a>(1), <a href='../notmuch-config-1/'>notmuch-config</a>(1), <a href='../notmuch-count-1/'>notmuch-count</a>(1), <a href='../notmuch-dump-1/'>notmuch-dump</a>(1), <a href='../notmuch-hooks-5/'>not-</a> + <a href='../notmuch-1/'>notmuch</a>(1), <a href='../notmuch-config-1/'>notmuch-config</a>(1), <a href='../notmuch-count-1/'>notmuch-count</a>(1), <a href='../notmuch-dump-1/'>notmuch-dump</a>(1), <a href='../notmuch-hooks-5/'>not-</a> <a href='../notmuch-hooks-5/'>much-hooks</a>(5), <a href='../notmuch-new-1/'>notmuch-new</a>(1), <a href='../notmuch-reply-1/'>notmuch-reply</a>(1), <a href='../notmuch-restore-1/'>notmuch-restore</a>(1), <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7), <a href='../notmuch-show-1/'>notmuch-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1) </pre> -<h2>Notmuch 0.14</h2> +<h2>Notmuch 0.15</h2> diff --git a/manpages/notmuch-search-terms-7.mdwn b/manpages/notmuch-search-terms-7.mdwn index f7d047c..595ef29 100644 --- a/manpages/notmuch-search-terms-7.mdwn +++ b/manpages/notmuch-search-terms-7.mdwn @@ -50,6 +50,8 @@ folder:<directory-path> + date:<since>..<until> + The <b>from:</b> prefix is used to match the name or address of the sender of an email message. @@ -81,37 +83,146 @@ the directory components below the top-level mail database path are available to be searched. - In addition to individual terms, multiple terms can be combined with - Boolean operators ( <b>and</b>, <b>or</b>, <b>not</b> , etc.). Each term in the query will - be implicitly connected by a logical AND if no explicit operator is - provided, (except that terms with a common prefix will be implicitly - combined with OR until we get Xapian defect #402 fixed). + The <b>date:</b> prefix can be used to restrict the results to only messages + within a particular time range (based on the Date: header) with a range + syntax of: - Parentheses can also be used to control the combination of the Boolean - operators, but will have to be protected from interpretation by the - shell, (such as by putting quotation marks around any parenthesized - expression). + date:<since>..<until> - Finally, results can be restricted to only messages within a particular - time range, (based on the Date: header) with a syntax of: + See <b>DATE</b> <b>AND</b> <b>TIME</b> <b>SEARCH</b> below for details on the range expression, and + supported syntax for <since> and <until> date and time expressions. + + The time range can also be specified using timestamps with a syntax of: <initial-timestamp>..<final-timestamp> Each timestamp is a number representing the number of seconds since - 1970-01-01 00:00:00 UTC. This is not the most convenient means of - expressing date ranges, but until notmuch is fixed to accept a more - convenient form, one can use the date program to construct timestamps. - For example, with the bash shell the following syntax would specify a - date range to return messages from 2009-10-01 until the current time: + 1970-01-01 00:00:00 UTC. + + In addition to individual terms, multiple terms can be combined with + Boolean operators ( <b>and</b>, <b>or</b>, <b>not</b> , etc.). Each term in the query will + be implicitly connected by a logical AND if no explicit operator is + provided, (except that terms with a common prefix will be implicitly + combined with OR until we get Xapian defect #402 fixed). + + Parentheses can also be used to control the combination of the Boolean + operators, but will have to be protected from interpretation by the + shell, (such as by putting quotation marks around any parenthesized + expression). +</pre> + +<h2>DATE AND TIME SEARCH</h2> +<pre> + notmuch understands a variety of standard and natural ways of express- + ing dates and times, both in absolute terms ("2012-10-24") and in rela- + tive terms ("yesterday"). Any number of relative terms can be combined + ("1 hour 25 minutes") and an absolute date/time can be combined with + relative terms to further adjust it. A non-exhaustive description of + the syntax supported for absolute and relative terms is given below. + + <b>The</b> <b>range</b> <b>expression</b> + + date:<since>..<until> + + The above expression restricts the results to only messages + from <since> to <until>, based on the Date: header. + + <since> and <until> can describe imprecise times, such as "yes- + terday". In this case, <since> is taken as the earliest time + it could describe (the beginning of yesterday) and <until> is + taken as the latest time it could describe (the end of yester- + day). Similarly, date:january..february matches from the begin- + ning of January to the end of February. + + Currently, we do not support spaces in range expressions. You + can replace the spaces with '_', or (in most cases) '-', or (in + some cases) leave the spaces out altogether. Examples in this + man page use spaces for clarity. + + Open-ended ranges are supported (since Xapian 1.2.1), i.e. it's + possible to specify date:..<until> or date:<since>.. to not + limit the start or end time, respectively. Pre-1.2.1 Xapian + does not report an error on open ended ranges, but it does not + work as expected either. + + Entering date:expr without ".." (for example date:yesterday) + won't work, as it's not interpreted as a range expression at + all. You can achieve the expected result by duplicating the + expr both sides of ".." (for example date:yesterday..yester- + day). + + <b>Relative</b> <b>date</b> <b>and</b> <b>time</b> + [N|number] (years|months|weeks|days|hours|hrs|minutes|mins|sec- + onds|secs) [...] + + All refer to past, can be repeated and will be accumulated. + + Units can be abbreviated to any length, with the otherwise + ambiguous single m being m for minutes and M for months. + + Number can also be written out one, two, ..., ten, dozen, hun- + dred. Additionally, the unit may be preceded by "last" or + "this" (e.g., "last week" or "this month"). + + When combined with absolute date and time, the relative date + and time specification will be relative from the specified + absolute date and time. + + Examples: 5M2d, two weeks + + <b>Supported</b> <b>absolute</b> <b>time</b> <b>formats</b> + H[H]:MM[:SS] [(am|a.m.|pm|p.m.)] + + H[H] (am|a.m.|pm|p.m.) + + HHMMSS + + now + + noon + + midnight + + Examples: 17:05, 5pm + + <b>Supported</b> <b>absolute</b> <b>date</b> <b>formats</b> + YYYY-MM[-DD] + + DD-MM[-[YY]YY] + + MM-YYYY + + M[M]/D[D][/[YY]YY] + + M[M]/YYYY + + D[D].M[M][.[YY]YY] + + D[D][(st|nd|rd|th)] Mon[thname] [YYYY] + + Mon[thname] D[D][(st|nd|rd|th)] [YYYY] + + Wee[kday] + + Month names can be abbreviated at three or more characters. + + Weekday names can be abbreviated at three or more characters. + + Examples: 2012-07-31, 31-07-2012, 7/31/2012, August 3 + + <b>Time</b> <b>zones</b> + (+|-)HH:MM + + (+|-)HH[MM] - $(date +%s -d 2009-10-01)..$(date +%s) + Some time zone codes, e.g. UTC, EET. </pre> <h2>SEE ALSO</h2> <pre> - <a href='../notmuch-1/'>notmuch</a>(1), <a href='../notmuch-config-1/'>notmuch-config</a>(1), <a href='../notmuch-count-1/'>notmuch-count</a>(1), <a href='../notmuch-dump-1/'>notmuch-dump</a>(1), <a href='../notmuch-hooks-5/'>not-</a> + <a href='../notmuch-1/'>notmuch</a>(1), <a href='../notmuch-config-1/'>notmuch-config</a>(1), <a href='../notmuch-count-1/'>notmuch-count</a>(1), <a href='../notmuch-dump-1/'>notmuch-dump</a>(1), <a href='../notmuch-hooks-5/'>not-</a> <a href='../notmuch-hooks-5/'>much-hooks</a>(5), <a href='../notmuch-new-1/'>notmuch-new</a>(1), <a href='../notmuch-reply-1/'>notmuch-reply</a>(1), <a href='../notmuch-restore-1/'>notmuch-restore</a>(1), <a href='../notmuch-search-1/'>notmuch-search</a>(1), <a href='../notmuch-show-1/'>notmuch-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1) </pre> -<h2>Notmuch 0.14</h2> +<h2>Notmuch 0.15</h2> diff --git a/manpages/notmuch-setup-1.mdwn b/manpages/notmuch-setup-1.mdwn index 98d0d81..3e9ad06 100644 --- a/manpages/notmuch-setup-1.mdwn +++ b/manpages/notmuch-setup-1.mdwn @@ -119,4 +119,4 @@ (server: irc.freenode.net, channel: #notmuch). </pre> -<h2>Notmuch 0.14</h2> +<h2>Notmuch 0.15</h2> diff --git a/manpages/notmuch-show-1.mdwn b/manpages/notmuch-show-1.mdwn index 2cbeff9..f5df849 100644 --- a/manpages/notmuch-show-1.mdwn +++ b/manpages/notmuch-show-1.mdwn @@ -29,10 +29,10 @@ If true, <b>notmuch</b> <b>show</b> outputs all messages in the thread of any message matching the search terms; if false, it outputs only - the matching messages. For <b>--format=json</b> this defaults to true. - For other formats, this defaults to false. + the matching messages. For <b>--format=json</b> and <b>--format=sexp</b> this + defaults to true. For other formats, this defaults to false. - <b>--format=(text|json|mbox|raw)</b> + <b>--format=(text|json|sexp|mbox|raw)</b> <b>text</b> (default for messages) @@ -52,99 +52,127 @@ automated processing. The nested structure of multipart MIME messages is reflected in nested JSON output. By default JSON output includes all messages in a matching - thread; that is, by default, <b>--format=json</b> sets - <b>--entire-thread</b> The caller can disable this behaviour by - setting <b>--entire-thread=false</b> + thread; that is, by default, + + <b>--format=json</b> sets <b>--entire-thread</b> The caller can disable + this behaviour by setting <b>--entire-thread=false</b> + + <b>sexp</b> + + The output is formatted as an S-Expression (sexp). This + format is more robust than the text format for automated + processing. The nested structure of multipart MIME messages + is reflected in nested S-Expression output. By default, S- + Expression output includes all messages in a matching + thread; that is, by default, + + <b>--format=sexp</b> sets <b>--entire-thread</b> The caller can disable + this behaviour by setting <b>--entire-thread=false</b> <b>mbox</b> - All matching messages are output in the traditional, Unix - mbox format with each message being prefixed by a line - beginning with "From " and a blank line separating each - message. Lines in the message content beginning with "From - " (preceded by zero or more '>' characters) have an - additional '>' character added. This reversible escaping is + All matching messages are output in the traditional, Unix + mbox format with each message being prefixed by a line + beginning with "From " and a blank line separating each + message. Lines in the message content beginning with "From + " (preceded by zero or more '>' characters) have an addi- + tional '>' character added. This reversible escaping is termed "mboxrd" format and described in detail here: http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html <b>raw</b> (default for a single part, see --part) - For a message or an attached message part, the original, - raw content of the email message is output. Consumers of - this format should expect to implement MIME decoding and + For a message or an attached message part, the original, + raw content of the email message is output. Consumers of + this format should expect to implement MIME decoding and similar functions. - For a single part (--part) the raw part content is output - after performing any necessary MIME decoding. Note that + For a single part (--part) the raw part content is output + after performing any necessary MIME decoding. Note that messages with a simple body still have two parts: part 0 is the whole message and part 1 is the body. - For a multipart part, the part headers and body (including + For a multipart part, the part headers and body (including all child parts) is output. The raw format must only be used with search terms matching single message. + <b>--format-version=N</b> + + Use the specified structured output format version. This is + intended for programs that invoke <a href='../notmuch-1/'>notmuch</a>(1) internally. If + omitted, the latest supported version will be used. + <b>--part=N</b> Output the single decoded MIME part N of a single message. The - search terms must match only a single message. Message parts - are numbered in a depth-first walk of the message MIME struc- - ture, and are identified in the 'json' or 'text' output for- - mats. + search terms must match only a single message. Message parts + are numbered in a depth-first walk of the message MIME struc- + ture, and are identified in the 'json', 'sexp' or 'text' output + formats. <b>--verify</b> - Compute and report the validity of any MIME cryptographic sig- - natures found in the selected content (ie. "multipart/signed" + Compute and report the validity of any MIME cryptographic sig- + natures found in the selected content (ie. "multipart/signed" parts). Status of the signature will be reported (currently on- - ly supported with --format=json), and the multipart/signed part - will be replaced by the signed data. + ly supported with --format=json and --format=sexp), and the + multipart/signed part will be replaced by the signed data. <b>--decrypt</b> - Decrypt any MIME encrypted parts found in the selected content - (ie. "multipart/encrypted" parts). Status of the decryption - will be reported (currently only supported with --format=json) - and the multipart/encrypted part will be replaced by the de- - crypted content. Implies --verify. + Decrypt any MIME encrypted parts found in the selected content + (ie. "multipart/encrypted" parts). Status of the decryption + will be reported (currently only supported with --format=json + and --format=sexp) and the multipart/encrypted part will be re- + placed by the decrypted content. Implies --verify. <b>--exclude=(true|false)</b> - Specify whether to omit threads only matching search.tag_ex- - clude from the search results (the default) or not. In either - case the excluded message will be marked with the exclude flag - (except when output=mbox when there is nowhere to put the + Specify whether to omit threads only matching search.tag_ex- + clude from the search results (the default) or not. In either + case the excluded message will be marked with the exclude flag + (except when output=mbox when there is nowhere to put the flag). - If --entire-thread is specified then complete threads are re- + If --entire-thread is specified then complete threads are re- turned regardless (with the excluded flag being set when appro- - priate) but threads that only match in an excluded message are + priate) but threads that only match in an excluded message are not returned when <b>--exclude=true.</b> The default is <b>--exclude=true.</b> <b>--body=(true|false)</b> - If true (the default) <b>notmuch</b> <b>show</b> includes the bodies of the - messages in the output; if false, bodies are omitted. - <b>--body=false</b> is only implemented for the json format and it is - incompatible with <b>--part</b> ><b>&</b>gt; <b>0.</b> + If true (the default) <b>notmuch</b> <b>show</b> includes the bodies of the + messages in the output; if false, bodies are omitted. + <b>--body=false</b> is only implemented for the json and sexp formats + and it is incompatible with <b>--part</b> ><b>&</b>gt; <b>0.</b> - This is useful if the caller only needs the headers as body- + This is useful if the caller only needs the headers as body- less output is much faster and substantially smaller. - A common use of <b>notmuch</b> <b>show</b> is to display a single thread of email + A common use of <b>notmuch</b> <b>show</b> is to display a single thread of email messages. For this, use a search term of "thread:<thread-id>" as can be seen in the first column of output from the <b>notmuch</b> <b>search</b> command. </pre> +<h2>EXIT STATUS</h2> +<pre> + This command supports the following special exit status codes + + <b>20</b> The requested format version is too old. + + <b>21</b> The requested format version is too new. +</pre> + <h2>SEE ALSO</h2> <pre> - <a href='../notmuch-1/'>notmuch</a>(1), <a href='../notmuch-config-1/'>notmuch-config</a>(1), <a href='../notmuch-count-1/'>notmuch-count</a>(1), <a href='../notmuch-dump-1/'>notmuch-dump</a>(1), <a href='../notmuch-hooks-5/'>not-</a> + <a href='../notmuch-1/'>notmuch</a>(1), <a href='../notmuch-config-1/'>notmuch-config</a>(1), <a href='../notmuch-count-1/'>notmuch-count</a>(1), <a href='../notmuch-dump-1/'>notmuch-dump</a>(1), <a href='../notmuch-hooks-5/'>not-</a> <a href='../notmuch-hooks-5/'>much-hooks</a>(5), <a href='../notmuch-new-1/'>notmuch-new</a>(1), <a href='../notmuch-reply-1/'>notmuch-reply</a>(1), <a href='../notmuch-restore-1/'>notmuch-restore</a>(1), <a href='../notmuch-search-1/'>notmuch-search</a>(1), <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1) </pre> -<h2>Notmuch 0.14</h2> +<h2>Notmuch 0.15</h2> diff --git a/manpages/notmuch-tag-1.mdwn b/manpages/notmuch-tag-1.mdwn index eee0325..1f0b8ca 100644 --- a/manpages/notmuch-tag-1.mdwn +++ b/manpages/notmuch-tag-1.mdwn @@ -8,7 +8,9 @@ <h2>SYNOPSIS</h2> <pre> - <b>notmuch</b> <b>tag</b> +<<u>tag</u>>|-<<u>tag</u>> [...] [--] <<u>search-term</u>>... + <b>notmuch</b> <b>tag</b> +<<u>tag</u>>|-<<u>tag</u>> [...] [--] <<u>search-term</u>> [...] + + <b>notmuch</b> <b>tag</b> --batch [ --input=<<u>filename</u>> ] </pre> <h2>DESCRIPTION</h2> @@ -16,26 +18,85 @@ Add/remove tags for all messages matching the search terms. See <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7) for details of the supported syntax for - <search-terms>. + <<u>search-term</u>>. Tags prefixed by '+' are added while those prefixed by '-' are removed. - For each message, tag removal is performed before tag addition. + For each message, tag changes are applied in the order they appear on + the command line. - The beginning of <search-terms> is recognized by the first argument - that begins with neither '+' nor '-'. Support for an initial search - term beginning with '+' or '-' is provided by allowing the user to + The beginning of the search terms is recognized by the first argument + that begins with neither '+' nor '-'. Support for an initial search + term beginning with '+' or '-' is provided by allowing the user to specify a "--" argument to separate the tags from the search terms. - <b>notmuch</b> <b>tag</b> updates the maildir flags according to tag changes if the + <b>notmuch</b> <b>tag</b> updates the maildir flags according to tag changes if the <b>maildir.synchronize</b>_<b>flags</b> configuration option is enabled. See <a href='../notmuch-config-1/'>notmuch-</a> <a href='../notmuch-config-1/'>config</a>(1) for details. + + Supported options for <b>tag</b> include + + <b>--batch</b> + + Read batch tagging operations from a file (stdin by default). + This is more efficient than repeated <b>notmuch</b> <b>tag</b> invocations. + See <b>TAG</b> <b>FILE</b> <b>FORMAT</b> below for the input format. This option is + not compatible with specifying tagging on the command line. + + <b>--input=</b><filename> + + Read input from given file, instead of from stdin. Implies + <b>--batch</b>. +</pre> + +<h2>TAG FILE FORMAT</h2> +<pre> + The input must consist of lines of the format: + + +<<u>tag</u>>|-<<u>tag</u>> [...] [--] <<u>query</u>> + + Each line is interpreted similarly to <b>notmuch</b> <b>tag</b> command line argu- + ments. The delimiter is one or more spaces ' '. Any characters in <<u>tag</u>> + <b>may</b> be hex-encoded with %NN where NN is the hexadecimal value of the + character. To hex-encode a character with a multi-byte UTF-8 encoding, + hex-encode each byte. Any spaces in <tag> <b>must</b> be hex-encoded as %20. + Any characters that are not part of <<u>tag</u>> <b>must</b> <b>not</b> be hex-encoded. + + In the future tag:"tag with spaces" style quoting may be supported for + <<u>tag</u>> as well; for this reason all double quote characters in <<u>tag</u>> + <b>should</b> be hex-encoded. + + The <<u>query</u>> should be quoted using Xapian boolean term quoting rules: + if a term contains whitespace or a close paren or starts with a double + quote, it must be enclosed in double quotes (not including any prefix) + and double quotes inside the term must be doubled (see below for exam- + ples). + + Leading and trailing space ' ' is ignored. Empty lines and lines begin- + ning with '#' are ignored. +</pre> + +<h3> EXAMPLE</h3> +<pre> + The following shows a valid input to batch tagging. Note that only the + isolated '*' acts as a wildcard. Also note the two different quotings + of the tag <b>space</b> <b>in</b> <b>tags</b> + +winner * + +foo::bar%25 -- (One and Two) or (One and tag:winner) + +found::it -- tag:foo::bar% + # ignore this line and the next + + +space%20in%20tags -- Two + # add tag '(tags)', among other stunts. + +crazy{ +(tags) +&are +#possible -- tag:"space in tags" + +match*crazy -- tag:crazy{ + +some_tag -- id:"this is ""nauty)""" </pre> <h2>SEE ALSO</h2> <pre> - <a href='../notmuch-1/'>notmuch</a>(1), <a href='../notmuch-config-1/'>notmuch-config</a>(1), <a href='../notmuch-count-1/'>notmuch-count</a>(1), <a href='../notmuch-dump-1/'>notmuch-dump</a>(1), <a href='../notmuch-hooks-5/'>not-</a> + <a href='../notmuch-1/'>notmuch</a>(1), <a href='../notmuch-config-1/'>notmuch-config</a>(1), <a href='../notmuch-count-1/'>notmuch-count</a>(1), <a href='../notmuch-dump-1/'>notmuch-dump</a>(1), <a href='../notmuch-hooks-5/'>not-</a> <a href='../notmuch-hooks-5/'>much-hooks</a>(5), <a href='../notmuch-new-1/'>notmuch-new</a>(1), <a href='../notmuch-reply-1/'>notmuch-reply</a>(1), <a href='../notmuch-restore-1/'>notmuch-restore</a>(1), <a href='../notmuch-search-1/'>notmuch-search</a>(1), <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7), <a href='../notmuch-show-1/'>notmuch-show</a>(1), </pre> -<h2>Notmuch 0.14</h2> +<h2>Notmuch 0.15</h2> |