From: David Bremner Date: Tue, 2 Jan 2018 01:50:24 +0000 (-0400) Subject: Merge tag '0.26_rc1' X-Git-Tag: 0.27_rc0~61 X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=commitdiff_plain;h=c8fc3d1428d86a653a23a5f8c32ea8ac52c8f160;hp=1ed211d042d5f413731f812b5af7e82819a6e8ae Merge tag '0.26_rc1' notmuch 0.26~rc1 release --- diff --git a/doc/man1/notmuch-address.rst b/doc/man1/notmuch-address.rst index 68415d13..c00d7d74 100644 --- a/doc/man1/notmuch-address.rst +++ b/doc/man1/notmuch-address.rst @@ -18,93 +18,89 @@ See **notmuch-search-terms(7)** for details of the supported syntax for Supported options for **address** include - ``--format=``\ (**json**\ \|\ **sexp**\ \|\ **text**\ \|\ **text0**) - Presents the results in either JSON, S-Expressions, newline - character separated plain-text (default), or null character - separated plain-text (compatible with **xargs(1)** -0 option - where available). - - ``--format-version=N`` - Use the specified structured output format version. This is - intended for programs that invoke **notmuch(1)** internally. If - omitted, the latest supported version will be used. - - ``--output=(sender|recipients|count|address)`` - - Controls which information appears in the output. This option - can be given multiple times to combine different outputs. - When neither --output=sender nor --output=recipients is - given, --output=sender is implied. - - **sender** - Output all addresses from the *From* header. - - Note: Searching for **sender** should be much faster than - searching for **recipients**, because sender addresses are - cached directly in the database whereas other addresses - need to be fetched from message files. - - **recipients** - Output all addresses from the *To*, *Cc* and *Bcc* - headers. - - **count** - Print the count of how many times was the address - encountered during search. - - Note: With this option, addresses are printed only after - the whole search is finished. This may take long time. - - **address** - Output only the email addresses instead of the full - mailboxes with names and email addresses. This option has - no effect on the JSON or S-Expression output formats. - - ``--deduplicate=(no|mailbox|address)`` - - Control the deduplication of results. - - **no** - Output all occurrences of addresses in the matching - messages. This is not applicable with --output=count. - - **mailbox** - Deduplicate addresses based on the full, case sensitive - name and email address, or mailbox. This is effectively - the same as piping the --deduplicate=no output to **sort | - uniq**, except for the order of results. This is the - default. - - **address** - Deduplicate addresses based on the case insensitive - address part of the mailbox. Of all the variants (with - different name or case), print the one occurring most - frequently among the matching messages. If --output=count - is specified, include all variants in the count. - - ``--sort=``\ (**newest-first**\ \|\ **oldest-first**) - This option can be used to present results in either - chronological order (**oldest-first**) or reverse chronological - order (**newest-first**). - - By default, results will be displayed in reverse chronological - order, (that is, the newest results will be displayed first). - - However, if either --output=count or --deduplicate=address is - specified, this option is ignored and the order of the results - is unspecified. - - ``--exclude=(true|false)`` - 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, **true**, prevents excluded messages from - matching the search terms. - - **false** allows excluded messages to match search terms and - appear in displayed results. +``--format=``\ (**json**\ \|\ **sexp**\ \|\ **text**\ \|\ **text0**) + Presents the results in either JSON, S-Expressions, newline + character separated plain-text (default), or null character + separated plain-text (compatible with **xargs(1)** -0 option where + available). + +``--format-version=N`` + Use the specified structured output format version. This is + intended for programs that invoke **notmuch(1)** internally. If + omitted, the latest supported version will be used. + +``--output=(sender|recipients|count|address)`` + Controls which information appears in the output. This option can + be given multiple times to combine different outputs. When + neither --output=sender nor --output=recipients is + given, --output=sender is implied. + + **sender** + Output all addresses from the *From* header. + + Note: Searching for **sender** should be much faster than + searching for **recipients**, because sender addresses are + cached directly in the database whereas other addresses need + to be fetched from message files. + + **recipients** + Output all addresses from the *To*, *Cc* and *Bcc* headers. + + **count** + Print the count of how many times was the address encountered + during search. + + Note: With this option, addresses are printed only after the + whole search is finished. This may take long time. + + **address** + Output only the email addresses instead of the full mailboxes + with names and email addresses. This option has no effect on + the JSON or S-Expression output formats. + +``--deduplicate=(no|mailbox|address)`` + Control the deduplication of results. + + **no** + Output all occurrences of addresses in the matching + messages. This is not applicable with --output=count. + + **mailbox** + Deduplicate addresses based on the full, case sensitive name + and email address, or mailbox. This is effectively the same as + piping the --deduplicate=no output to **sort | uniq**, except + for the order of results. This is the default. + + **address** + Deduplicate addresses based on the case insensitive address + part of the mailbox. Of all the variants (with different name + or case), print the one occurring most frequently among the + matching messages. If --output=count is specified, include all + variants in the count. + +``--sort=``\ (**newest-first**\ \|\ **oldest-first**) + This option can be used to present results in either chronological + order (**oldest-first**) or reverse chronological order + (**newest-first**). + + By default, results will be displayed in reverse chronological + order, (that is, the newest results will be displayed first). + + However, if either --output=count or --deduplicate=address is + specified, this option is ignored and the order of the results is + unspecified. + +``--exclude=(true|false)`` + 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, **true**, prevents excluded messages from + matching the search terms. + + **false** allows excluded messages to match search terms and + appear in displayed results. EXIT STATUS =========== diff --git a/doc/man1/notmuch-compact.rst b/doc/man1/notmuch-compact.rst index 25692c5b..b05593ec 100644 --- a/doc/man1/notmuch-compact.rst +++ b/doc/man1/notmuch-compact.rst @@ -24,14 +24,14 @@ process (which may be quite long) to protect data integrity. Supported options for **compact** include - ``--backup=``\ - Save the current database to the given directory before - replacing it with the compacted database. The backup directory - must not exist and it must reside on the same mounted filesystem - as the current database. - - ``--quiet`` - Do not report database compaction progress to stdout. +``--backup=``\ + Save the current database to the given directory before replacing + it with the compacted database. The backup directory must not + exist and it must reside on the same mounted filesystem as the + current database. + +``--quiet`` + Do not report database compaction progress to stdout. ENVIRONMENT =========== diff --git a/doc/man1/notmuch-config.rst b/doc/man1/notmuch-config.rst index 9d6ff107..f9fb672a 100644 --- a/doc/man1/notmuch-config.rst +++ b/doc/man1/notmuch-config.rst @@ -21,203 +21,189 @@ Items marked **[STORED IN DATABASE]** are only in the database. They should not be placed in the configuration file, and should be accessed programmatically as described in the SYNOPSIS above. - **get** - The value of the specified configuration item is printed to - stdout. If the item has multiple values (it is a list), each - value is separated by a newline character. +**get** + The value of the specified configuration item is printed to + stdout. If the item has multiple values (it is a list), each value + is separated by a newline character. - **set** - The specified configuration item is set to the given value. To - specify a multiple-value item (a list), provide each value as a - separate command-line argument. +**set** + The specified configuration item is set to the given value. To + specify a multiple-value item (a list), provide each value as a + separate command-line argument. - If no values are provided, the specified configuration item will - be removed from the configuration file. + If no values are provided, the specified configuration item will + be removed from the configuration file. - **list** - Every configuration item is printed to stdout, each on a - separate line of the form: +**list** + Every configuration item is printed to stdout, each on a separate + line of the form:: *section*.\ *item*\ =\ *value* - No additional whitespace surrounds the dot or equals sign - characters. In a multiple-value item (a list), the values are - separated by semicolon characters. + No additional whitespace surrounds the dot or equals sign + characters. In a multiple-value item (a list), the values are + separated by semicolon characters. The available configuration items are described below. - **database.path** - The top-level directory where your mail currently exists and to - where mail will be delivered in the future. Files should be - individual email messages. Notmuch will store its database - within a sub-directory of the path configured here named - ``.notmuch``. +**database.path** + The top-level directory where your mail currently exists and to + where mail will be delivered in the future. Files should be + individual email messages. Notmuch will store its database within + a sub-directory of the path configured here named ``.notmuch``. - Default: ``$MAILDIR`` variable if set, otherwise ``$HOME/mail``. + Default: ``$MAILDIR`` variable if set, otherwise ``$HOME/mail``. + +**user.name** + Your full name. + + Default: ``$NAME`` variable if set, otherwise read from + ``/etc/passwd``. - **user.name** - Your full name. +**user.primary\_email** + Your primary email address. - Default: ``$NAME`` variable if set, otherwise read from - ``/etc/passwd``. + Default: ``$EMAIL`` variable if set, otherwise constructed from + the username and hostname of the current machine. - **user.primary\_email** - Your primary email address. - - Default: ``$EMAIL`` variable if set, otherwise constructed from the - username and hostname of the current machine. - - **user.other\_email** - A list of other email addresses at which you receive email. - - Default: not set. - - **new.tags** - A list of tags that will be added to all messages incorporated - by **notmuch new**. - - Default: ``unread;inbox``. - - **new.ignore** - A list to specify files and directories that will not be - searched for messages by **notmuch new**. Each entry in the - list is either: - - A file or a directory name, without path, that will be - ignored, regardless of the location in the mail store - directory hierarchy. - - Or: - - A regular expression delimited with // that will be matched - against the path of the file or directory relative to the - database path. Matching files and directories will be - ignored. The beginning and end of string must be explictly - anchored. For example, /.*/foo$/ would match "bar/foo" and - "bar/baz/foo", but not "foo" or "bar/foobar". - - Default: empty list. - - **search.exclude\_tags** - A list of tags that will be excluded from search results by - default. Using an excluded tag in a query will override that - exclusion. - - Default: empty list. Note that **notmuch-setup(1)** puts - ``deleted;spam`` here when creating new configuration file. - - - - **maildir.synchronize\_flags** - If true, then the following maildir flags (in message filenames) - will be synchronized with the corresponding notmuch tags: - - +--------+-----------------------------------------------+ - | Flag | Tag | - +========+===============================================+ - | D | draft | - +--------+-----------------------------------------------+ - | F | flagged | - +--------+-----------------------------------------------+ - | P | passed | - +--------+-----------------------------------------------+ - | R | replied | - +--------+-----------------------------------------------+ - | S | unread (added when 'S' flag is not present) | - +--------+-----------------------------------------------+ - - The **notmuch new** command will notice flag changes in - filenames and update tags, while the **notmuch tag** and - **notmuch restore** commands will notice tag changes and update - flags in filenames. - - If there have been any changes in the maildir (new messages - added, old ones removed or renamed, maildir flags changed, - etc.), it is advisable to run **notmuch new** before **notmuch - tag** or **notmuch restore** commands to ensure the tag changes - are properly synchronized to the maildir flags, as the commands - expect the database and maildir to be in sync. - - Default: ``true``. - - **crypto.gpg_path** - - Name (or full path) of gpg binary to use in verification and - decryption of PGP/MIME messages. NOTE: This configuration - item is deprecated, and will be ignored if notmuch is built - against GMime 3.0 or later. - - Default: ``gpg``. - - **index.decrypt** - - **[STORED IN DATABASE]** - - Policy for decrypting encrypted messages during indexing. - Must be one of: ``false``, ``auto``, ``nostash``, or - ``true``. - - When indexing an encrypted e-mail message, if this variable is - set to ``true``, notmuch will try to decrypt the message and - index the cleartext, stashing a copy of any discovered session - keys for the message. If ``auto``, it will try to index the - cleartext if a stashed session key is already known for the message - (e.g. from a previous copy), but will not try to access your - secret keys. Use ``false`` to avoid decrypting even when a - stashed session key is already present. - - ``nostash`` is the same as ``true`` except that it will not - stash newly-discovered session keys in the database. - - From the command line (i.e. during **notmuch-new(1)**, - **notmuch-insert(1)**, or **notmuch-reindex(1)**), the user - can override the database's stored decryption policy with the - ``--decrypt=`` option. - - Here is a table that summarizes the functionality of each of - these policies: - - +------------------------+-------+------+---------+------+ - | | false | auto | nostash | true | - +========================+=======+======+=========+======+ - | Index cleartext using | | X | X | X | - | stashed session keys | | | | | - +------------------------+-------+------+---------+------+ - | Index cleartext | | | X | X | - | using secret keys | | | | | - +------------------------+-------+------+---------+------+ - | Stash session keys | | | | X | - +------------------------+-------+------+---------+------+ - | Delete stashed session | X | | | | - | keys on reindex | | | | | - +------------------------+-------+------+---------+------+ - - Stashed session keys are kept in the database as properties - associated with the message. See ``session-key`` in - **notmuch-properties(7)** for more details about how they can - be useful. - - Be aware that the notmuch index is likely sufficient (and a - stashed session key is certainly sufficient) to reconstruct - the cleartext of the message itself, so please ensure that the - notmuch message index is adequately protected. DO NOT USE - ``index.decrypt=true`` or ``index.decrypt=nostash`` without - considering the security of your index. - - Default: ``auto``. - - **built_with.** - - Compile time feature . Current possibilities include - "compact" (see **notmuch-compact(1)**) - and "field_processor" (see **notmuch-search-terms(7)**). - - **query.** - - **[STORED IN DATABASE]** - Expansion for named query called . See - **notmuch-search-terms(7)** for more information about named - queries. +**user.other\_email** + A list of other email addresses at which you receive email. + + Default: not set. + +**new.tags** + A list of tags that will be added to all messages incorporated by + **notmuch new**. + + Default: ``unread;inbox``. + +**new.ignore** + A list to specify files and directories that will not be searched + for messages by **notmuch new**. Each entry in the list is either: + + A file or a directory name, without path, that will be ignored, + regardless of the location in the mail store directory hierarchy. + + Or: + + A regular expression delimited with // that will be matched + against the path of the file or directory relative to the database + path. Matching files and directories will be ignored. The + beginning and end of string must be explictly anchored. For + example, /.*/foo$/ would match "bar/foo" and "bar/baz/foo", but + not "foo" or "bar/foobar". + + Default: empty list. + +**search.exclude\_tags** + A list of tags that will be excluded from search results by + default. Using an excluded tag in a query will override that + exclusion. + + Default: empty list. Note that **notmuch-setup(1)** puts + ``deleted;spam`` here when creating new configuration file. + +**maildir.synchronize\_flags** + If true, then the following maildir flags (in message filenames) + will be synchronized with the corresponding notmuch tags: + + +--------+-----------------------------------------------+ + | Flag | Tag | + +========+===============================================+ + | D | draft | + +--------+-----------------------------------------------+ + | F | flagged | + +--------+-----------------------------------------------+ + | P | passed | + +--------+-----------------------------------------------+ + | R | replied | + +--------+-----------------------------------------------+ + | S | unread (added when 'S' flag is not present) | + +--------+-----------------------------------------------+ + + The **notmuch new** command will notice flag changes in filenames + and update tags, while the **notmuch tag** and **notmuch restore** + commands will notice tag changes and update flags in filenames. + + If there have been any changes in the maildir (new messages added, + old ones removed or renamed, maildir flags changed, etc.), it is + advisable to run **notmuch new** before **notmuch tag** or + **notmuch restore** commands to ensure the tag changes are + properly synchronized to the maildir flags, as the commands expect + the database and maildir to be in sync. + + Default: ``true``. + +**crypto.gpg_path** + Name (or full path) of gpg binary to use in verification and + decryption of PGP/MIME messages. NOTE: This configuration item is + deprecated, and will be ignored if notmuch is built against GMime + 3.0 or later. + + Default: ``gpg``. + +**index.decrypt** **[STORED IN DATABASE]** + Policy for decrypting encrypted messages during indexing. Must be + one of: ``false``, ``auto``, ``nostash``, or ``true``. + + When indexing an encrypted e-mail message, if this variable is set + to ``true``, notmuch will try to decrypt the message and index the + cleartext, stashing a copy of any discovered session keys for the + message. If ``auto``, it will try to index the cleartext if a + stashed session key is already known for the message (e.g. from a + previous copy), but will not try to access your secret keys. Use + ``false`` to avoid decrypting even when a stashed session key is + already present. + + ``nostash`` is the same as ``true`` except that it will not stash + newly-discovered session keys in the database. + + From the command line (i.e. during **notmuch-new(1)**, + **notmuch-insert(1)**, or **notmuch-reindex(1)**), the user can + override the database's stored decryption policy with the + ``--decrypt=`` option. + + Here is a table that summarizes the functionality of each of these + policies: + + +------------------------+-------+------+---------+------+ + | | false | auto | nostash | true | + +========================+=======+======+=========+======+ + | Index cleartext using | | X | X | X | + | stashed session keys | | | | | + +------------------------+-------+------+---------+------+ + | Index cleartext | | | X | X | + | using secret keys | | | | | + +------------------------+-------+------+---------+------+ + | Stash session keys | | | | X | + +------------------------+-------+------+---------+------+ + | Delete stashed session | X | | | | + | keys on reindex | | | | | + +------------------------+-------+------+---------+------+ + + Stashed session keys are kept in the database as properties + associated with the message. See ``session-key`` in + **notmuch-properties(7)** for more details about how they can be + useful. + + Be aware that the notmuch index is likely sufficient (and a + stashed session key is certainly sufficient) to reconstruct the + cleartext of the message itself, so please ensure that the notmuch + message index is adequately protected. DO NOT USE + ``index.decrypt=true`` or ``index.decrypt=nostash`` without + considering the security of your index. + + Default: ``auto``. + +**built_with.** + Compile time feature . Current possibilities include + "compact" (see **notmuch-compact(1)**) and "field_processor" (see + **notmuch-search-terms(7)**). + +**query.** **[STORED IN DATABASE]** + Expansion for named query called . See + **notmuch-search-terms(7)** for more information about named + queries. ENVIRONMENT =========== diff --git a/doc/man1/notmuch-count.rst b/doc/man1/notmuch-count.rst index 35a2e5e8..9ca20dab 100644 --- a/doc/man1/notmuch-count.rst +++ b/doc/man1/notmuch-count.rst @@ -22,39 +22,38 @@ See **notmuch-search-terms(7)** for details of the supported syntax for Supported options for **count** include - ``--output=(messages|threads|files)`` - - **messages** - Output the number of matching messages. This is the default. - - **threads** - Output the number of matching threads. - - **files** - Output the number of files associated with matching - messages. This may be bigger than the number of matching - messages due to duplicates (i.e. multiple files having the - same message-id). - - ``--exclude=(true|false)`` - Specify whether to omit messages matching search.tag\_exclude - from the count (the default) or not. - - ``--batch`` - Read queries from a file (stdin by default), one per line, and - output the number of matching messages (or threads) to stdout, - one per line. On an empty input line the count of all messages - (or threads) in the database will be output. This option is not - compatible with specifying search terms on the command line. - - ``--lastmod`` - Append lastmod (counter for number of database updates) and UUID - to the output. lastmod values are only comparable between databases - with the same UUID. - - ``--input=``\ - Read input from given file, instead of from stdin. Implies - ``--batch``. +``--output=(messages|threads|files)`` + **messages** + Output the number of matching messages. This is the default. + + **threads** + Output the number of matching threads. + + **files** + Output the number of files associated with matching + messages. This may be bigger than the number of matching + messages due to duplicates (i.e. multiple files having the + same message-id). + +``--exclude=(true|false)`` + Specify whether to omit messages matching search.tag\_exclude from + the count (the default) or not. + +``--batch`` + Read queries from a file (stdin by default), one per line, and + output the number of matching messages (or threads) to stdout, one + per line. On an empty input line the count of all messages (or + threads) in the database will be output. This option is not + compatible with specifying search terms on the command line. + +``--lastmod`` + Append lastmod (counter for number of database updates) and UUID + to the output. lastmod values are only comparable between + databases with the same UUID. + +``--input=``\ + Read input from given file, instead of from stdin. Implies + ``--batch``. SEE ALSO ======== diff --git a/doc/man1/notmuch-dump.rst b/doc/man1/notmuch-dump.rst index 7bc57d29..f8ec4868 100644 --- a/doc/man1/notmuch-dump.rst +++ b/doc/man1/notmuch-dump.rst @@ -26,86 +26,76 @@ the remaining arguments are search terms. Supported options for **dump** include - ``--gzip`` - Compress the output in a format compatible with **gzip(1)**. - - ``--format=(sup|batch-tag)`` - Notmuch restore supports two plain text dump formats, both with one - message-id per line, followed by a list of tags. - - **batch-tag** - - The default **batch-tag** dump format is intended to more - robust against malformed message-ids and tags containing - whitespace or non-\ **ascii(7)** characters. Each line has - the form - - +<*encoded-tag*\ > +<*encoded-tag*\ > ... -- - id:<*quoted-message-id*\ > - - Tags are hex-encoded by replacing every byte not matching - the regex **[A-Za-z0-9@=.,\_+-]** with **%nn** 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 whitespace 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 **notmuch-tag(1)**; - note that the single message-id query is mandatory for - **notmuch-restore(1)**. - - **sup** - - The **sup** 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 **notmuch restore** command provides you a way to - import all of your tags (or labels as sup calls - them). Each line has the following form - - <*message-id*\ > **(** <*tag*\ > ... **)** - - with zero or more tags are separated by spaces. Note that - (malformed) message-ids may contain arbitrary non-null - characters. Note also that tags with spaces will not be - correctly restored with this format. - - ``--include=(config|properties|tags)`` - +``--gzip`` + Compress the output in a format compatible with **gzip(1)**. + +``--format=(sup|batch-tag)`` + Notmuch restore supports two plain text dump formats, both with + one message-id per line, followed by a list of tags. + + **batch-tag** + The default **batch-tag** dump format is intended to more + robust against malformed message-ids and tags containing + whitespace or non-\ **ascii(7)** characters. Each line has the + form:: + + +<*encoded-tag*\ > +<*encoded-tag*\ > ... -- id:<*quoted-message-id*\ > + + Tags are hex-encoded by replacing every byte not matching the + regex **[A-Za-z0-9@=.,\_+-]** with **%nn** 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 whitespace 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 + **notmuch-tag(1)**; note that the single message-id query is + mandatory for **notmuch-restore(1)**. + + **sup** + The **sup** 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 + **notmuch restore** command provides you a way to import all + of your tags (or labels as sup calls them). Each line has the + following form:: + + <*message-id*\ > **(** <*tag*\ > ... **)** + + with zero or more tags are separated by spaces. Note that + (malformed) message-ids may contain arbitrary non-null + characters. Note also that tags with spaces will not be + correctly restored with this format. + +``--include=(config|properties|tags)`` Control what kind of metadata is included in the output. - **config** - + **config** Output configuration data stored in the database. Each line starts with "#@ ", followed by a space separated key-value pair. Both key and value are hex encoded if needed. - **properties** - + **properties** Output per-message (key,value) metadata. Each line starts with "#= ", followed by a message id, and a space separated list of key=value pairs. Ids, keys and values are hex encoded if needed. See **notmuch-properties(7)** for more details. - **tags** - + **tags** Output per-message boolean metadata, namely tags. See *format* above for description of the output. - The default is to include all available types of data. The - option can be specified multiple times to select some subset. As - of version 3 of the dump format, there is a header line of the - following form + The default is to include all available types of data. The option + can be specified multiple times to select some subset. As of + version 3 of the dump format, there is a header line of the + following form:: - | - | #notmuch-dump <*format*>:<*version*> <*included*> + #notmuch-dump <*format*>:<*version*> <*included*> - where <*included*> is a comma separated list of the above - options. + where <*included*> is a comma separated list of the above options. - ``--output=``\ - Write output to given file instead of stdout. +``--output=``\ + Write output to given file instead of stdout. SEE ALSO ======== diff --git a/doc/man1/notmuch-emacs-mua.rst b/doc/man1/notmuch-emacs-mua.rst index 87787e20..a0476136 100644 --- a/doc/man1/notmuch-emacs-mua.rst +++ b/doc/man1/notmuch-emacs-mua.rst @@ -15,49 +15,49 @@ subject, recipients, and message body, or mailto: URL. Supported options for **emacs-mua** include - ``-h, --help`` - Display help. +``-h, --help`` + Display help. - ``-s, --subject=``\ - Specify the subject of the message. +``-s, --subject=``\ + Specify the subject of the message. - ``--to=``\ - Specify a recipient (To). +``--to=``\ + Specify a recipient (To). - ``-c, --cc=``\ - Specify a carbon-copy (Cc) recipient. +``-c, --cc=``\ + Specify a carbon-copy (Cc) recipient. - ``-b, --bcc=``\ - Specify a blind-carbon-copy (Bcc) recipient. +``-b, --bcc=``\ + Specify a blind-carbon-copy (Bcc) recipient. - ``-i, --body=``\ - Specify a file to include into the body of the message. +``-i, --body=``\ + Specify a file to include into the body of the message. - ``--hello`` - Go to the Notmuch hello screen instead of the message composition - window if no message composition parameters are given. +``--hello`` + Go to the Notmuch hello screen instead of the message composition + window if no message composition parameters are given. - ``--no-window-system`` - Even if a window system is available, use the current terminal. +``--no-window-system`` + Even if a window system is available, use the current terminal. - ``--client`` - Use **emacsclient**, rather than **emacs**. For - **emacsclient** to work, you need an already running Emacs - with a server, or use ``--auto-daemon``. +``--client`` + Use **emacsclient**, rather than **emacs**. For **emacsclient** to + work, you need an already running Emacs with a server, or use + ``--auto-daemon``. - ``--auto-daemon`` - Automatically start Emacs in daemon mode, if the Emacs server - is not running. Applicable with ``--client``. Implies - ``--create-frame``. +``--auto-daemon`` + Automatically start Emacs in daemon mode, if the Emacs server is + not running. Applicable with ``--client``. Implies + ``--create-frame``. - ``--create-frame`` - Create a new frame instead of trying to use the current Emacs - frame. Applicable with ``--client``. This will be required - when Emacs is running (or automatically started with - ``--auto-daemon``) in daemon mode. +``--create-frame`` + Create a new frame instead of trying to use the current Emacs + frame. Applicable with ``--client``. This will be required when + Emacs is running (or automatically started with ``--auto-daemon``) + in daemon mode. - ``--print`` - Output the resulting elisp to stdout instead of evaluating it. +``--print`` + Output the resulting elisp to stdout instead of evaluating it. The supported positional parameters and short options are a compatible subset of the **mutt** MUA command-line options. The options and diff --git a/doc/man1/notmuch-insert.rst b/doc/man1/notmuch-insert.rst index 1a3dfe98..47884515 100644 --- a/doc/man1/notmuch-insert.rst +++ b/doc/man1/notmuch-insert.rst @@ -31,48 +31,46 @@ more details on hooks. Option arguments must appear before any tag operation arguments. Supported options for **insert** include - ``--folder=<``\ folder\ **>** - Deliver the message to the specified folder, relative to the - top-level directory given by the value of **database.path**. The - default is the empty string, which means delivering to the - top-level directory. - - ``--create-folder`` - Try to create the folder named by the ``--folder`` option, if it - does not exist. Otherwise the folder must already exist for mail - delivery to succeed. - - ``--keep`` - Keep the message file if indexing fails, and keep the message - indexed if applying tags or maildir flag synchronization - fails. Ignore these errors and return exit status 0 to - indicate successful mail delivery. - - ``--no-hooks`` - Prevent hooks from being run. - - ``--decrypt=(true|nostash|auto|false)`` - - If ``true`` and the message is encrypted, try to decrypt the - message while indexing, stashing any session keys discovered. - If ``auto``, and notmuch already knows about a session key for - the message, it will try decrypting using that session key but - will not try to access the user's secret keys. If decryption - is successful, index the cleartext itself. Either way, the - message is always stored to disk in its original form - (ciphertext). - - ``nostash`` is the same as ``true`` except that it will not - stash newly-discovered session keys in the database. - - Be aware that the index is likely sufficient (and a stashed - session key is certainly sufficient) to reconstruct the - cleartext of the message itself, so please ensure that the - notmuch message index is adequately protected. DO NOT USE - ``--decrypt=true`` or ``--decrypt=nostash`` without - considering the security of your index. - - See also ``index.decrypt`` in **notmuch-config(1)**. +``--folder=<``\ folder\ **>** + Deliver the message to the specified folder, relative to the + top-level directory given by the value of **database.path**. The + default is the empty string, which means delivering to the + top-level directory. + +``--create-folder`` + Try to create the folder named by the ``--folder`` option, if it + does not exist. Otherwise the folder must already exist for mail + delivery to succeed. + +``--keep`` + Keep the message file if indexing fails, and keep the message + indexed if applying tags or maildir flag synchronization + fails. Ignore these errors and return exit status 0 to indicate + successful mail delivery. + +``--no-hooks`` + Prevent hooks from being run. + +``--decrypt=(true|nostash|auto|false)`` + If ``true`` and the message is encrypted, try to decrypt the + message while indexing, stashing any session keys discovered. If + ``auto``, and notmuch already knows about a session key for the + message, it will try decrypting using that session key but will + not try to access the user's secret keys. If decryption is + successful, index the cleartext itself. Either way, the message + is always stored to disk in its original form (ciphertext). + + ``nostash`` is the same as ``true`` except that it will not stash + newly-discovered session keys in the database. + + Be aware that the index is likely sufficient (and a stashed + session key is certainly sufficient) to reconstruct the cleartext + of the message itself, so please ensure that the notmuch message + index is adequately protected. DO NOT USE ``--decrypt=true`` or + ``--decrypt=nostash`` without considering the security of your + index. + + See also ``index.decrypt`` in **notmuch-config(1)**. EXIT STATUS =========== diff --git a/doc/man1/notmuch-new.rst b/doc/man1/notmuch-new.rst index 3ddd4621..16af5492 100644 --- a/doc/man1/notmuch-new.rst +++ b/doc/man1/notmuch-new.rst @@ -37,29 +37,27 @@ details on hooks. Supported options for **new** include - ``--no-hooks`` - Prevents hooks from being run. - - ``--quiet`` - Do not print progress or results. - - ``--decrypt=(true|nostash|auto|false)`` - - If ``true``, when encountering an encrypted message, try to - decrypt it while indexing, and stash any discovered session - keys. If ``auto``, try to use any session key already known - to belong to this message, but do not attempt to use the - user's secret keys. If decryption is successful, index the - cleartext of the message. - - Be aware that the index is likely sufficient (and the session - key is certainly sufficient) to reconstruct the cleartext of - the message itself, so please ensure that the notmuch message - index is adequately protected. DO NOT USE ``--decrypt=true`` - or ``--decrypt=nostash`` without considering the security of - your index. - - See also ``index.decrypt`` in **notmuch-config(1)**. +``--no-hooks`` + Prevents hooks from being run. + +``--quiet`` + Do not print progress or results. + +``--decrypt=(true|nostash|auto|false)`` + If ``true``, when encountering an encrypted message, try to + decrypt it while indexing, and stash any discovered session keys. + If ``auto``, try to use any session key already known to belong to + this message, but do not attempt to use the user's secret keys. + If decryption is successful, index the cleartext of the message. + + Be aware that the index is likely sufficient (and the session key + is certainly sufficient) to reconstruct the cleartext of the + message itself, so please ensure that the notmuch message index is + adequately protected. DO NOT USE ``--decrypt=true`` or + ``--decrypt=nostash`` without considering the security of your + index. + + See also ``index.decrypt`` in **notmuch-config(1)**. EXIT STATUS =========== diff --git a/doc/man1/notmuch-reindex.rst b/doc/man1/notmuch-reindex.rst index 8b3083cf..54490f29 100644 --- a/doc/man1/notmuch-reindex.rst +++ b/doc/man1/notmuch-reindex.rst @@ -21,29 +21,28 @@ messages using the supplied options. Supported options for **reindex** include - ``--decrypt=(true|nostash|auto|false)`` - - If ``true``, when encountering an encrypted message, try to - decrypt it while reindexing, stashing any session keys - discovered. If ``auto``, and notmuch already knows about a - session key for the message, it will try decrypting using that - session key but will not try to access the user's secret keys. - If decryption is successful, index the cleartext itself. - - ``nostash`` is the same as ``true`` except that it will not - stash newly-discovered session keys in the database. - - If ``false``, notmuch reindex will also delete any stashed - session keys for all messages matching the search terms. - - Be aware that the index is likely sufficient (and a stashed - session key is certainly sufficient) to reconstruct the - cleartext of the message itself, so please ensure that the - notmuch message index is adequately protected. DO NOT USE - ``--decrypt=true`` or ``--decrypt=nostash`` without - considering the security of your index. - - See also ``index.decrypt`` in **notmuch-config(1)**. +``--decrypt=(true|nostash|auto|false)`` + If ``true``, when encountering an encrypted message, try to + decrypt it while reindexing, stashing any session keys discovered. + If ``auto``, and notmuch already knows about a session key for the + message, it will try decrypting using that session key but will + not try to access the user's secret keys. If decryption is + successful, index the cleartext itself. + + ``nostash`` is the same as ``true`` except that it will not stash + newly-discovered session keys in the database. + + If ``false``, notmuch reindex will also delete any stashed session + keys for all messages matching the search terms. + + Be aware that the index is likely sufficient (and a stashed + session key is certainly sufficient) to reconstruct the cleartext + of the message itself, so please ensure that the notmuch message + index is adequately protected. DO NOT USE ``--decrypt=true`` or + ``--decrypt=nostash`` without considering the security of your + index. + + See also ``index.decrypt`` in **notmuch-config(1)**. SEE ALSO ======== diff --git a/doc/man1/notmuch-reply.rst b/doc/man1/notmuch-reply.rst index 1b62e075..c893ba04 100644 --- a/doc/man1/notmuch-reply.rst +++ b/doc/man1/notmuch-reply.rst @@ -34,64 +34,62 @@ The resulting message template is output to stdout. Supported options for **reply** include - ``--format=``\ (**default**\ \|\ **json**\ \|\ **sexp**\ \|\ **headers-only**) - - **default** - Includes subject and quoted message body as an RFC 2822 - message. - - **json** - Produces JSON 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. - - **sexp** - 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. - - **headers-only** - Only produces In-Reply-To, References, To, Cc, and Bcc - headers. - - ``--format-version=N`` - Use the specified structured output format version. This is - intended for programs that invoke **notmuch(1)** internally. If - omitted, the latest supported version will be used. - - ``--reply-to=``\ (**all**\ \|\ **sender**) - - **all** (default) - Replies to all addresses. - - **sender** - 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. - - ``--decrypt=(false|auto|true)`` - - If ``true``, decrypt any MIME encrypted parts found in the - selected content (i.e., "multipart/encrypted" parts). Status - of the decryption will be reported (currently only supported - with --format=json and --format=sexp), and on successful - decryption the multipart/encrypted part will be replaced by - the decrypted content. - - If ``auto``, and a session key is already known for the - message, then it will be decrypted, but notmuch will not try - to access the user's secret keys. - - Use ``false`` to avoid even automatic decryption. - - Non-automatic decryption expects a functioning - **gpg-agent(1)** to provide any needed credentials. Without - one, the decryption will likely fail. - - Default: ``auto`` +``--format=``\ (**default**\ \|\ **json**\ \|\ **sexp**\ \|\ **headers-only**) + **default** + Includes subject and quoted message body as an RFC 2822 + message. + + **json** + Produces JSON 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. + + **sexp** + 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. + + **headers-only** + Only produces In-Reply-To, References, To, Cc, and Bcc + headers. + +``--format-version=N`` + Use the specified structured output format version. This is + intended for programs that invoke **notmuch(1)** internally. If + omitted, the latest supported version will be used. + +``--reply-to=``\ (**all**\ \|\ **sender**) + **all** (default) + Replies to all addresses. + + **sender** + 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. + +``--decrypt=(false|auto|true)`` + + If ``true``, decrypt any MIME encrypted parts found in the + selected content (i.e., "multipart/encrypted" parts). Status + of the decryption will be reported (currently only supported + with --format=json and --format=sexp), and on successful + decryption the multipart/encrypted part will be replaced by + the decrypted content. + + If ``auto``, and a session key is already known for the + message, then it will be decrypted, but notmuch will not try + to access the user's secret keys. + + Use ``false`` to avoid even automatic decryption. + + Non-automatic decryption expects a functioning + **gpg-agent(1)** to provide any needed credentials. Without + one, the decryption will likely fail. + + Default: ``auto`` See **notmuch-search-terms(7)** for details of the supported syntax for . diff --git a/doc/man1/notmuch-restore.rst b/doc/man1/notmuch-restore.rst index b578af1f..c0f47f26 100644 --- a/doc/man1/notmuch-restore.rst +++ b/doc/man1/notmuch-restore.rst @@ -16,68 +16,62 @@ The input is read from the given filename, if any, or from stdin. Supported options for **restore** include - ``--accumulate`` - 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. - - ``--format=(sup|batch-tag|auto)`` - 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 **notmuch-dump(1)**. - - **sup** - The **sup** 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 - **notmuch restore** command provides you a way to import all - of your tags (or labels as sup calls them). - - **batch-tag** - The **batch-tag** dump format is intended to more robust - against malformed message-ids and tags containing whitespace - or non-\ **ascii(7)** characters. See **notmuch-dump(1)** - for details on this format. - - **notmuch restore** updates the maildir flags according to - tag changes if the **maildir.synchronize\_flags** - configuration option is enabled. See **notmuch-config(1)** - for details. - - **auto** - 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 format - contains no parentheses, should be accurate. - - ``--include=(config|properties|tags)`` - - Control what kind of metadata is restored. - - **config** - - Restore configuration data to the database. Each configuration line starts - with "#@ ", followed by a space separated key-value pair. - Both key and value are hex encoded if needed. - - **properties** - - Restore per-message (key,value) metadata. Each line starts - with "#= ", followed by a message id, and a space separated - list of key=value pairs. Ids, keys and values are hex - encoded if needed. See **notmuch-properties(7)** for more - details. - - **tags** - - Restore per-message metadata, namely tags. See *format* above - for more details. - - The default is to restore all available types of data. The - option can be specified multiple times to select some subset. - - ``--input=``\ - Read input from given file instead of stdin. +``--accumulate`` + 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. + +``--format=(sup|batch-tag|auto)`` + 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 **notmuch-dump(1)**. + + **sup** + The **sup** 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 + **notmuch restore** command provides you a way to import all + of your tags (or labels as sup calls them). + + **batch-tag** + The **batch-tag** dump format is intended to more robust + against malformed message-ids and tags containing whitespace + or non-\ **ascii(7)** characters. See **notmuch-dump(1)** for + details on this format. + + **notmuch restore** updates the maildir flags according to tag + changes if the **maildir.synchronize\_flags** configuration + option is enabled. See **notmuch-config(1)** for details. + + **auto** + 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 format contains + no parentheses, should be accurate. + +``--include=(config|properties|tags)`` + Control what kind of metadata is restored. + + **config** + Restore configuration data to the database. Each configuration + line starts with "#@ ", followed by a space separated + key-value pair. Both key and value are hex encoded if needed. + + **properties** + Restore per-message (key,value) metadata. Each line starts + with "#= ", followed by a message id, and a space separated + list of key=value pairs. Ids, keys and values are hex encoded + if needed. See **notmuch-properties(7)** for more details. + + **tags** + Restore per-message metadata, namely tags. See *format* above + for more details. + + The default is to restore all available types of data. The option + can be specified multiple times to select some subset. + +``--input=``\ + Read input from given file instead of stdin. GZIPPED INPUT ============= diff --git a/doc/man1/notmuch-search.rst b/doc/man1/notmuch-search.rst index 67c1ce90..181058c6 100644 --- a/doc/man1/notmuch-search.rst +++ b/doc/man1/notmuch-search.rst @@ -24,118 +24,118 @@ See **notmuch-search-terms(7)** for details of the supported syntax for Supported options for **search** include - ``--format=``\ (**json**\ \|\ **sexp**\ \|\ **text**\ \|\ **text0**) - Presents the results in either JSON, S-Expressions, newline - character separated plain-text (default), or null character - separated plain-text (compatible with **xargs(1)** -0 option - where available). - - ``--format-version=N`` - Use the specified structured output format version. This is - intended for programs that invoke **notmuch(1)** internally. If - omitted, the latest supported version will be used. - - ``--output=(summary|threads|messages|files|tags)`` - - **summary** - 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 and - the subject. In the case where a thread contains multiple files for - some messages, the total number of files is printed in parentheses - (see below for an example). - - **threads** - Output the thread IDs of all threads with any message - matching the 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). - - **messages** - 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 - (--format=json), or as an S-Expression list (--format=sexp). - - **files** - Output the filenames of all messages matching the search - terms, 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). - - Note that each message may have multiple filenames - associated with it. All of them are included in the output - (unless limited with the --duplicate=N option). This may - be particularly confusing for **folder:** or **path:** - searches in a specified directory, as the messages may - have duplicates in other directories that are included in - the output, although these files alone would not match the - search. - - **tags** - Output all tags that appear on any message matching the - search terms, 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). - - ``--sort=``\ (**newest-first**\ \|\ **oldest-first**) - This option can be used to present results in either - chronological order (**oldest-first**) or reverse chronological - order (**newest-first**). - - Note: The thread order will be distinct between these two - options (beyond being simply reversed). When sorting by - **oldest-first** the threads will be sorted by the oldest - message in each thread, but when sorting by **newest-first** the - threads will be sorted by the newest message in each thread. - - By default, results will be displayed in reverse chronological - order, (that is, the newest results will be displayed first). - - ``--offset=[-]N`` - Skip displaying the first N results. With the leading '-', start - at the Nth result from the end. - - ``--limit=N`` - Limit the number of displayed results to N. - - ``--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, **true**, prevents excluded messages from - matching the search terms. - - **all** additionally prevents excluded messages from appearing - in displayed results, in effect behaving as though the excluded +``--format=``\ (**json**\ \|\ **sexp**\ \|\ **text**\ \|\ **text0**) + Presents the results in either JSON, S-Expressions, newline + character separated plain-text (default), or null character + separated plain-text (compatible with **xargs(1)** -0 option where + available). + +``--format-version=N`` + Use the specified structured output format version. This is + intended for programs that invoke **notmuch(1)** internally. If + omitted, the latest supported version will be used. + +``--output=(summary|threads|messages|files|tags)`` + **summary** + 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 and the + subject. In the case where a thread contains multiple files + for some messages, the total number of files is printed in + parentheses (see below for an example). + + **threads** + Output the thread IDs of all threads with any message matching + the 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). + + **messages** + 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 (--format=json), + or as an S-Expression list (--format=sexp). + + **files** + Output the filenames of all messages matching the search + terms, 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). + + Note that each message may have multiple filenames associated + with it. All of them are included in the output (unless + limited with the --duplicate=N option). This may be + particularly confusing for **folder:** or **path:** searches + in a specified directory, as the messages may have duplicates + in other directories that are included in the output, although + these files alone would not match the search. + + **tags** + Output all tags that appear on any message matching the search + terms, 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). + +``--sort=``\ (**newest-first**\ \|\ **oldest-first**) + This option can be used to present results in either chronological + order (**oldest-first**) or reverse chronological order + (**newest-first**). + + Note: The thread order will be distinct between these two options + (beyond being simply reversed). When sorting by **oldest-first** + the threads will be sorted by the oldest message in each thread, + but when sorting by **newest-first** the threads will be sorted by + the newest message in each thread. + + By default, results will be displayed in reverse chronological + order, (that is, the newest results will be displayed first). + +``--offset=[-]N`` + Skip displaying the first N results. With the leading '-', start + at the Nth result from the end. + +``--limit=N`` + Limit the number of displayed results to N. + +``--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. + + **true** (default) + Prevent excluded messages from matching the search terms. + + **all** + Additionally prevent excluded messages from appearing in + displayed results, in effect behaving as though the excluded messages do not exist. - **false** allows excluded messages to match search terms and - appear in displayed results. Excluded messages are still marked - in the relevant outputs. - - **flag** only has an effect when ``--output=summary``. The - output is almost identical to **false**, but the "match count" - is the number of matching non-excluded messages in the thread, - rather than the number of matching messages. - - ``--duplicate=N`` - For ``--output=files``, output the Nth filename associated - with each message matching the query (N is 1-based). If N is - greater than the number of files associated with the message, - don't print anything. - - For ``--output=messages``, only output message IDs of messages - matching the search terms that have at least N filenames - associated with them. - - Note that this option is orthogonal with the **folder:** search - prefix. The prefix matches messages based on filenames. This - option filters filenames of the matching messages. + **false** + Allow excluded messages to match search terms and appear in + displayed results. Excluded messages are still marked in the + relevant outputs. + + **flag** + Only has an effect when ``--output=summary``. The output is + almost identical to **false**, but the "match count" is the + number of matching non-excluded messages in the thread, rather + than the number of matching messages. + +``--duplicate=N`` + For ``--output=files``, output the Nth filename associated with + each message matching the query (N is 1-based). If N is greater + than the number of files associated with the message, don't print + anything. + + For ``--output=messages``, only output message IDs of messages + matching the search terms that have at least N filenames + associated with them. + + Note that this option is orthogonal with the **folder:** search + prefix. The prefix matches messages based on filenames. This + option filters filenames of the matching messages. EXAMPLE ======= diff --git a/doc/man1/notmuch-show.rst b/doc/man1/notmuch-show.rst index 7d2b38cb..2b825ccc 100644 --- a/doc/man1/notmuch-show.rst +++ b/doc/man1/notmuch-show.rst @@ -23,149 +23,143 @@ post-processor (such as the emacs interface to notmuch). Supported options for **show** include - ``--entire-thread=(true|false)`` - If true, **notmuch show** outputs all messages in the thread of - any message matching the search terms; if false, it outputs only - the matching messages. For ``--format=json`` and - ``--format=sexp`` this defaults to true. For other formats, this - defaults to false. - - ``--format=(text|json|sexp|mbox|raw)`` - - **text** (default for messages) - The default plain-text format has all text-content MIME - parts decoded. Various components in the output, - (**message**, **header**, **body**, **attachment**, and MIME - **part**), will be delimited by easily-parsed markers. Each - marker consists of a Control-L character (ASCII decimal 12), - the name of the marker, and then either an opening or - closing brace, ('{' or '}'), to either open or close the - component. For a multipart MIME message, these parts will be - nested. - - **json** - The output is formatted with Javascript Object Notation - (JSON). This format is more robust than the text format for - 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, - ``--format=json`` sets ``--entire-thread``. The caller can - disable this behaviour by setting ``--entire-thread=false``. - The JSON output is always encoded as UTF-8 and any message - content included in the output will be charset-converted to - UTF-8. - - **sexp** - The output is formatted as the Lisp s-expression (sexp) - equivalent of the JSON format above. Objects are formatted - as property lists whose keys are keywords (symbols preceded - by a colon). True is formatted as ``t`` and both false and - null are formatted as ``nil``. As for JSON, the s-expression - output is always encoded as UTF-8. - - **mbox** - 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 termed - "mboxrd" format and described in detail here: +``--entire-thread=(true|false)`` + If true, **notmuch show** outputs all messages in the thread of + any message matching the search terms; if false, it outputs only + the matching messages. For ``--format=json`` and ``--format=sexp`` + this defaults to true. For other formats, this defaults to false. + +``--format=(text|json|sexp|mbox|raw)`` + **text** (default for messages) + The default plain-text format has all text-content MIME parts + decoded. Various components in the output, (**message**, + **header**, **body**, **attachment**, and MIME **part**), will + be delimited by easily-parsed markers. Each marker consists of + a Control-L character (ASCII decimal 12), the name of the + marker, and then either an opening or closing brace, ('{' or + '}'), to either open or close the component. For a multipart + MIME message, these parts will be nested. + + **json** + The output is formatted with Javascript Object Notation + (JSON). This format is more robust than the text format for + 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, ``--format=json`` sets ``--entire-thread``. The + caller can disable this behaviour by setting + ``--entire-thread=false``. The JSON output is always encoded + as UTF-8 and any message content included in the output will + be charset-converted to UTF-8. + + **sexp** + The output is formatted as the Lisp s-expression (sexp) + equivalent of the JSON format above. Objects are formatted as + property lists whose keys are keywords (symbols preceded by a + colon). True is formatted as ``t`` and both false and null are + formatted as ``nil``. As for JSON, the s-expression output is + always encoded as UTF-8. + + **mbox** + 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 termed "mboxrd" format and + described in detail here: http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html - **raw** (default if --part is given) - Write the raw bytes of the given MIME part of a message to - standard out. For this format, it is an error to specify a - query that matches more than one message. - - If the specified part is a leaf part, this outputs the - body of the part after performing content transfer - decoding (but no charset conversion). This is suitable for - saving attachments, for example. - - For a multipart or message part, the output includes the - part headers as well as the body (including all child - parts). No decoding is performed because multipart and - message parts cannot have non-trivial content transfer - encoding. Consumers of this may need to implement MIME - decoding and similar functions. - - ``--format-version=N`` - Use the specified structured output format version. This is - intended for programs that invoke **notmuch(1)** internally. If - omitted, the latest supported version will be used. - - ``--part=N`` - 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 structure, - and are identified in the 'json', 'sexp' or 'text' output - formats. - - Note that even a message with no MIME structure or a single - body part still has two MIME parts: part 0 is the whole - message (headers and body) and part 1 is just the body. - - ``--verify`` - Compute and report the validity of any MIME cryptographic - signatures found in the selected content (ie. "multipart/signed" - parts). Status of the signature will be reported (currently only - supported with --format=json and --format=sexp), and the - multipart/signed part will be replaced by the signed data. - - ``--decrypt=(false|auto|true)`` - If ``true``, decrypt any MIME encrypted parts found in the - selected content (i.e. "multipart/encrypted" parts). Status of - the decryption will be reported (currently only supported - with --format=json and --format=sexp) and on successful - decryption the multipart/encrypted part will be replaced by - the decrypted content. - - If ``auto``, and a session key is already known for the - message, then it will be decrypted, but notmuch will not try - to access the user's keys. - - Use ``false`` to avoid even automatic decryption. - - Non-automatic decryption expects a functioning - **gpg-agent(1)** to provide any needed credentials. Without - one, the decryption will fail. - - Note: ``true`` implies --verify. - - Default: ``auto`` - - ``--exclude=(true|false)`` - Specify whether to omit threads only matching - search.tag\_exclude 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 - returned regardless (with the excluded flag being set when - appropriate) but threads that only match in an excluded message - are not returned when ``--exclude=true.`` - - The default is ``--exclude=true.`` - - ``--body=(true|false)`` - If true (the default) **notmuch show** includes the bodies of - the messages in the output; if false, bodies are omitted. - ``--body=false`` is only implemented for the json and sexp - formats and it is incompatible with ``--part > 0.`` - - This is useful if the caller only needs the headers as body-less - output is much faster and substantially smaller. - - ``--include-html`` - Include "text/html" parts as part of the output (currently only - supported with --format=json and --format=sexp). By default, - unless ``--part=N`` is used to select a specific part or - ``--include-html`` is used to include all "text/html" parts, no - part with content type "text/html" is included in the output. + **raw** (default if --part is given) + Write the raw bytes of the given MIME part of a message to + standard out. For this format, it is an error to specify a + query that matches more than one message. + + If the specified part is a leaf part, this outputs the body of + the part after performing content transfer decoding (but no + charset conversion). This is suitable for saving attachments, + for example. + + For a multipart or message part, the output includes the part + headers as well as the body (including all child parts). No + decoding is performed because multipart and message parts + cannot have non-trivial content transfer encoding. Consumers + of this may need to implement MIME decoding and similar + functions. + +``--format-version=N`` + Use the specified structured output format version. This is + intended for programs that invoke **notmuch(1)** internally. If + omitted, the latest supported version will be used. + +``--part=N`` + 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 structure, and + are identified in the 'json', 'sexp' or 'text' output formats. + + Note that even a message with no MIME structure or a single body + part still has two MIME parts: part 0 is the whole message + (headers and body) and part 1 is just the body. + +``--verify`` + Compute and report the validity of any MIME cryptographic + signatures found in the selected content (ie. "multipart/signed" + parts). Status of the signature will be reported (currently only + supported with --format=json and --format=sexp), and the + multipart/signed part will be replaced by the signed data. + +``--decrypt=(false|auto|true)`` + If ``true``, decrypt any MIME encrypted parts found in the + selected content (i.e. "multipart/encrypted" parts). Status of + the decryption will be reported (currently only supported + with --format=json and --format=sexp) and on successful + decryption the multipart/encrypted part will be replaced by + the decrypted content. + + If ``auto``, and a session key is already known for the + message, then it will be decrypted, but notmuch will not try + to access the user's keys. + + Use ``false`` to avoid even automatic decryption. + + Non-automatic decryption expects a functioning + **gpg-agent(1)** to provide any needed credentials. Without + one, the decryption will fail. + + Note: ``true`` implies --verify. + + Default: ``auto`` + +``--exclude=(true|false)`` + Specify whether to omit threads only matching search.tag\_exclude + 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 returned + regardless (with the excluded flag being set when appropriate) but + threads that only match in an excluded message are not returned + when ``--exclude=true.`` + + The default is ``--exclude=true.`` + +``--body=(true|false)`` + If true (the default) **notmuch show** includes the bodies of the + messages in the output; if false, bodies are omitted. + ``--body=false`` is only implemented for the json and sexp formats + and it is incompatible with ``--part > 0.`` + + This is useful if the caller only needs the headers as body-less + output is much faster and substantially smaller. + +``--include-html`` + Include "text/html" parts as part of the output (currently only + supported with --format=json and --format=sexp). By default, + unless ``--part=N`` is used to select a specific part or + ``--include-html`` is used to include all "text/html" parts, no + part with content type "text/html" is included in the output. A common use of **notmuch show** is to display a single thread of email messages. For this, use a search term of "thread:" as can be diff --git a/doc/man1/notmuch-tag.rst b/doc/man1/notmuch-tag.rst index 88e454ba..c2324f5a 100644 --- a/doc/man1/notmuch-tag.rst +++ b/doc/man1/notmuch-tag.rst @@ -32,23 +32,22 @@ the **maildir.synchronize\_flags** configuration option is enabled. See Supported options for **tag** include - ``--remove-all`` - Remove all tags from each message matching the search terms - before applying the tag changes appearing on the command line. - This means setting the tags of each message to the tags to be - added. If there are no tags to be added, the messages will have - no tags. - - ``--batch`` - Read batch tagging operations from a file (stdin by default). - This is more efficient than repeated **notmuch tag** - invocations. See `TAG FILE FORMAT <#tag_file_format>`__ below - for the input format. This option is not compatible with - specifying tagging on the command line. - - ``--input=``\ - Read input from given file, instead of from stdin. Implies - ``--batch``. +``--remove-all`` + Remove all tags from each message matching the search terms before + applying the tag changes appearing on the command line. This + means setting the tags of each message to the tags to be added. If + there are no tags to be added, the messages will have no tags. + +``--batch`` + Read batch tagging operations from a file (stdin by default). + This is more efficient than repeated **notmuch tag** + invocations. See `TAG FILE FORMAT <#tag_file_format>`__ below for + the input format. This option is not compatible with specifying + tagging on the command line. + +``--input=``\ + Read input from given file, instead of from stdin. Implies + ``--batch``. TAG FILE FORMAT =============== diff --git a/doc/man1/notmuch.rst b/doc/man1/notmuch.rst index 358f42e8..d2cd8da5 100644 --- a/doc/man1/notmuch.rst +++ b/doc/man1/notmuch.rst @@ -39,28 +39,27 @@ OPTIONS Supported global options for ``notmuch`` include - ``--help`` [command-name] - Print a synopsis of available commands and exit. - With an optional command name, show the man page - for that subcommand. +``--help`` [command-name] + Print a synopsis of available commands and exit. With an optional + command name, show the man page for that subcommand. - ``--version`` - Print the installed version of notmuch, and exit. +``--version`` + Print the installed version of notmuch, and exit. - ``--config=FILE`` - Specify the configuration file to use. This overrides any - configuration file specified by ${NOTMUCH\_CONFIG}. +``--config=FILE`` + Specify the configuration file to use. This overrides any + configuration file specified by ${NOTMUCH\_CONFIG}. - ``--uuid=HEX`` - Enforce that the database UUID (a unique identifier which - persists until e.g. the database is compacted) - is HEX; exit with an error if it is not. This is useful to - detect rollover in modification counts on messages. You can - find this UUID using e.g. ``notmuch count --lastmod`` +``--uuid=HEX`` + Enforce that the database UUID (a unique identifier which persists + until e.g. the database is compacted) is HEX; exit with an error + if it is not. This is useful to detect rollover in modification + counts on messages. You can find this UUID using e.g. ``notmuch + count --lastmod`` All global options except ``--config`` can also be specified after the -command. For example, ``notmuch subcommand --uuid=HEX`` is -equivalent to ``notmuch --uuid=HEX subcommand``. +command. For example, ``notmuch subcommand --uuid=HEX`` is equivalent +to ``notmuch --uuid=HEX subcommand``. COMMANDS ======== diff --git a/doc/man5/notmuch-hooks.rst b/doc/man5/notmuch-hooks.rst index f07e4dab..de2ed0c2 100644 --- a/doc/man5/notmuch-hooks.rst +++ b/doc/man5/notmuch-hooks.rst @@ -17,34 +17,33 @@ have executable permissions. The currently available hooks are described below. - **pre-new** - This hook is invoked by the **new** command before scanning or - importing new messages into the database. If this hook exits - with a non-zero status, notmuch will abort further processing of - the **new** command. - - Typically this hook is used for fetching or delivering new mail - to be imported into the database. - - **post-new** - This hook is invoked by the **new** command after new messages - have been imported into the database and initial tags have been - applied. The hook will not be run if there have been any errors - during the scan or import. - - Typically this hook is used to perform additional query-based - tagging on the imported messages. - - **post-insert** - - This hook is invoked by the **insert** command after the - message has been delivered, added to the database, and initial - tags have been applied. The hook will not be run if there have - been any errors during the message delivery; what is regarded - as successful delivery depends on the ``--keep`` option. - - Typically this hook is used to perform additional query-based - tagging on the delivered messages. +**pre-new** + This hook is invoked by the **new** command before scanning or + importing new messages into the database. If this hook exits with + a non-zero status, notmuch will abort further processing of the + **new** command. + + Typically this hook is used for fetching or delivering new mail to + be imported into the database. + +**post-new** + This hook is invoked by the **new** command after new messages + have been imported into the database and initial tags have been + applied. The hook will not be run if there have been any errors + during the scan or import. + + Typically this hook is used to perform additional query-based + tagging on the imported messages. + +**post-insert** + This hook is invoked by the **insert** command after the message + has been delivered, added to the database, and initial tags have + been applied. The hook will not be run if there have been any + errors during the message delivery; what is regarded as successful + delivery depends on the ``--keep`` option. + + Typically this hook is used to perform additional query-based + tagging on the delivered messages. SEE ALSO ======== diff --git a/doc/man7/notmuch-properties.rst b/doc/man7/notmuch-properties.rst index 07d36a1a..802e6763 100644 --- a/doc/man7/notmuch-properties.rst +++ b/doc/man7/notmuch-properties.rst @@ -54,7 +54,6 @@ The following properties are set by notmuch internally in the course of its normal activity. **index.decryption** - If a message contains encrypted content, and notmuch tries to decrypt that content during indexing, it will add the property ``index.decryption=success`` when the cleartext was successfully