doc: unify definition list usage across man pages

Make all parameter descriptions etc. use reStructuredText definition
lists with uniform style and indentation. Remove redundant indentation
from around the lists. Remove blank lines between term lines and
definition blocks. Use four spaces for indentation.

This is almost completely whitespace and paragraph reflow changes.

15 files changed, 838 insertions, 888 deletions

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=``\ <directory>
-        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=``\ <directory>
+    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.<name>**
-
-        Compile time feature <name>. Current possibilities include
-        "compact" (see **notmuch-compact(1)**)
-        and "field_processor" (see **notmuch-search-terms(7)**).
-
-    **query.<name>**
-
-        **[STORED IN DATABASE]**
-        Expansion for named query called <name>. 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.<name>**
+    Compile time feature <name>. Current possibilities include
+    "compact" (see **notmuch-compact(1)**) and "field_processor" (see
+    **notmuch-search-terms(7)**).
+
+**query.<name>** **[STORED IN DATABASE]**
+    Expansion for named query called <name>. 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=``\ <filename>
-        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=``\ <filename>
+    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