Merge tag 'debian/0.36-1' into debian/bullseye-backports

notmuch release 0.36-1 for unstable (sid) [dgit]

[dgit distro=debian no-split --quilt=linear]

6 files changed, 204 insertions, 125 deletions

diff --git a/doc/man1/notmuch-config.rst b/doc/man1/notmuch-config.rst
index 41e1338b..acc5ecec 100644
--- a/doc/man1/notmuch-config.rst
+++ b/doc/man1/notmuch-config.rst
@@ -55,22 +55,19 @@ The available configuration items are described below. Non-absolute
 paths are presumed relative to `$HOME` for items in section
 **database**.
 
-database.path
-    Notmuch will store its database here, (in
-    sub-directory named ``.notmuch`` if **database.mail\_root**
-    is unset).
-
-    Default: see :ref:`database`
+built_with.<name>
+    Compile time feature <name>. Current possibilities include
+    "retry_lock" (configure option, included by default).
+    (since notmuch 0.30, "compact" and "field_processor" are
+    always included.)
 
-database.mail_root
-    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.
+database.autocommit
 
-    History: this configuration value was introduced in notmuch 0.32.
+    How often to commit transactions to disk. `0` means wait until
+    command completes, otherwise an integer `n` specifies to commit to
+    disk after every `n` completed transactions.
 
-    Default: For compatibility with older configurations, the value of
-    database.path is used if **database.mail\_root** is unset.
+    History: this configuration value was introduced in notmuch 0.33.
 
 database.backup_dir
     Directory to store tag dumps when upgrading database.
@@ -88,109 +85,26 @@ database.hook_dir
 
     Default: See HOOKS, below.
 
-database.autocommit
-
-    How often to commit transactions to disk. `0` means wait until
-    command completes, otherwise an integer `n` specifies to commit to
-    disk after every `n` completed transactions.
-
-    History: this configuration value was introduced in notmuch 0.33.
-
-user.name
-    Your full name.
-
-    Default: ``$NAME`` variable if set, otherwise read from
-    ``/etc/passwd``.
-
-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 :any:`notmuch-new(1)`. 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 explicitly 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 :any:`notmuch-setup(1)` puts
-    ``deleted;spam`` here when creating new configuration file.
-
-.. _show.extra_headers:
-
-show.extra\_headers
+.. _database.mail_root:
 
-    By default :any:`notmuch-show(1)` includes the following headers
-    in structured output if they are present in the message:
-    `Subject`, `From`, `To`, `Cc`, `Bcc`, `Reply-To`, `Date`. This
-    option allows the specification of a list of further
-    headers to output.
-
-    History: This configuration value was introduced in notmuch 0.35.
-
-    Default: empty list.
+database.mail_root
+    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.
 
-maildir.synchronize\_flags
-    If true, then the following maildir flags (in message filenames)
-    will be synchronized with the corresponding notmuch tags:
+    History: this configuration value was introduced in notmuch 0.32.
 
-    +--------+-----------------------------------------------+
-    | Flag   | Tag                                           |
-    +========+===============================================+
-    | D      | draft                                         |
-    +--------+-----------------------------------------------+
-    | F      | flagged                                       |
-    +--------+-----------------------------------------------+
-    | P      | passed                                        |
-    +--------+-----------------------------------------------+
-    | R      | replied                                       |
-    +--------+-----------------------------------------------+
-    | S      | unread (added when 'S' flag is not present)   |
-    +--------+-----------------------------------------------+
+    Default: For compatibility with older configurations, the value of
+    database.path is used if **database.mail\_root** is unset.
 
-    The :any:`notmuch-new(1)` command will notice flag changes in
-    filenames and update tags, while the :any:`notmuch-tag(1)` and
-    :any:`notmuch-restore(1)` commands will notice tag changes and
-    update flags in filenames.
+database.path
+    Notmuch will store its database here, (in
+    sub-directory named ``.notmuch`` if **database.mail\_root**
+    is unset).
 
-    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 :any:`notmuch-new(1)` before
-    :any:`notmuch-tag(1)` or :any:`notmuch-restore(1)` 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: see :ref:`database`
 
-    Default: ``true``.
+.. _index.decrypt:
 
 index.decrypt
     Policy for decrypting encrypted messages during indexing.  Must be
@@ -245,6 +159,8 @@ index.decrypt
 
     Default: ``auto``.
 
+.. _index.header:
+
 index.header.<prefix>
     Define the query prefix <prefix>, based on a mail header. For
     example ``index.header.List=List-Id`` will add a probabilistic
@@ -254,22 +170,121 @@ index.header.<prefix>
     supported. See :any:`notmuch-search-terms(7)` for a list of existing
     prefixes, and an explanation of probabilistic prefixes.
 
-built_with.<name>
-    Compile time feature <name>. Current possibilities include
-    "retry_lock" (configure option, included by default).
-    (since notmuch 0.30, "compact" and "field_processor" are
-    always included.)
+.. _maildir.synchronize_flags:
+
+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 :any:`notmuch-new(1)` command will notice flag changes in
+    filenames and update tags, while the :any:`notmuch-tag(1)` and
+    :any:`notmuch-restore(1)` 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 :any:`notmuch-new(1)` before
+    :any:`notmuch-tag(1)` or :any:`notmuch-restore(1)` 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``.
+
+.. _new.ignore:
+
+new.ignore
+    A list to specify files and directories that will not be searched
+    for messages by :any:`notmuch-new(1)`. 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 explicitly anchored. For
+    example, /.*/foo$/ would match "bar/foo" and "bar/baz/foo", but
+    not "foo" or "bar/foobar".
+
+    Default: empty list.
+
+.. _new.tags:
+
+new.tags
+    A list of tags that will be added to all messages incorporated by
+    **notmuch new**.
+
+    Default: ``unread;inbox``.
 
 query.<name>
     Expansion for named query called <name>. See
     :any:`notmuch-search-terms(7)` for more information about named
     queries.
 
+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 :any:`notmuch-setup(1)` puts
+    ``deleted;spam`` here when creating new configuration file.
+
+.. _show.extra_headers:
+
+show.extra\_headers
+
+    By default :any:`notmuch-show(1)` includes the following headers
+    in structured output if they are present in the message:
+    `Subject`, `From`, `To`, `Cc`, `Bcc`, `Reply-To`, `Date`. This
+    option allows the specification of a list of further
+    headers to output.
+
+    History: This configuration value was introduced in notmuch 0.35.
+
+    Default: empty list.
+
 squery.<name>
     Expansion for named query called <name>, using s-expression syntax. See
     :any:`notmuch-sexp-queries(7)` for more information about s-expression
     queries.
 
+user.name
+    Your full name.
+
+    Default: ``$NAME`` variable if set, otherwise read from
+    ``/etc/passwd``.
+
+user.other\_email
+    A list of other email addresses at which you receive email
+    (see also, :ref:`user.primary_email <user.primary_email>`).
+
+    Default: not set.
+
+.. _user.primary_email:
+
+user.primary\_email
+    Your primary email address.
+
+    Default: ``$EMAIL`` variable if set, otherwise constructed from
+    the username and hostname of the current machine.
+
 FILES
 =====
 
diff --git a/doc/man1/notmuch-insert.rst b/doc/man1/notmuch-insert.rst
index da9ca791..fe2bf26b 100644
--- a/doc/man1/notmuch-insert.rst
+++ b/doc/man1/notmuch-insert.rst
@@ -14,12 +14,12 @@ DESCRIPTION
 
 **notmuch insert** reads a message from standard input and delivers it
 into the maildir directory given by configuration option
-**database.mail_root**, then incorporates the message into the notmuch
+:ref:`database.mail_root <database.mail_root>`, then incorporates the message into the notmuch
 database. It is an alternative to using a separate tool to deliver the
 message then running :any:`notmuch-new(1)` afterwards.
 
 The new message will be tagged with the tags specified by the
-**new.tags** configuration option, then by operations specified on the
+:ref:`new.tags <new.tags>` configuration option, then by operations specified on the
 command-line: tags prefixed by '+' are added while those prefixed by '-'
 are removed.
 
@@ -86,7 +86,17 @@ Supported options for **insert** include
    ``--decrypt=nostash`` without considering the security of your
    index.
 
-   See also ``index.decrypt`` in :any:`notmuch-config(1)`.
+   See also :ref:`index.decrypt <index.decrypt>` in :any:`notmuch-config(1)`.
+
+CONFIGURATION
+=============
+
+Indexing is influenced by the configuration options
+:ref:`index.decrypt <index.decrypt>` and :ref:`index.header
+<index.header>`.  Tagging
+is controlled by :ref:`new.tags <new.tags>` and
+:ref:`maildir.synchronize_flags <maildir.synchronize_flags>`.  See
+:any:`notmuch-config(1)` for details.
 
 EXIT STATUS
 ===========
diff --git a/doc/man1/notmuch-new.rst b/doc/man1/notmuch-new.rst
index 9cb4a54e..398f8813 100644
--- a/doc/man1/notmuch-new.rst
+++ b/doc/man1/notmuch-new.rst
@@ -78,6 +78,16 @@ Supported options for **new** include
    to optimize the scanning of directories for new mail. This option turns
    that optimization off.
 
+CONFIGURATION
+=============
+
+Indexing is influenced by the configuration options
+:ref:`index.decrypt <index.decrypt>`, :ref:`index.header
+<index.header>`, and :ref:`new.ignore <new.ignore>`.  Tagging
+is controlled by :ref:`new.tags <new.tags>` and
+:ref:`maildir.synchronize_flags <maildir.synchronize_flags>`.  See
+:any:`notmuch-config(1)` for details.
+
 EXIT STATUS
 ===========
 
diff --git a/doc/man5/notmuch-hooks.rst b/doc/man5/notmuch-hooks.rst
index 0ab5efbc..d778bdb8 100644
--- a/doc/man5/notmuch-hooks.rst
+++ b/doc/man5/notmuch-hooks.rst
@@ -30,9 +30,9 @@ pre-new
 
 post-new
     This hook is invoked by the :any:`notmuch-new(1)` 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.
+    any 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.
diff --git a/doc/man7/notmuch-search-terms.rst b/doc/man7/notmuch-search-terms.rst
index e80cc7d0..4f616b7e 100644
--- a/doc/man7/notmuch-search-terms.rst
+++ b/doc/man7/notmuch-search-terms.rst
@@ -169,6 +169,12 @@ property:<key>=<value>
     can be present on a given message with several different values.
     See :any:`notmuch-properties(7)` for more details.
 
+sexp:<subquery>
+    The **sexp:** prefix allows subqueries in the format
+    documented in :any:`notmuch-sexp-queries(7)`. Note that subqueries containing
+    spaces must be quoted, and any embedded double quotes must be escaped
+    (see :any:`quoting`).
+
 User defined prefixes are also supported, see :any:`notmuch-config(1)` for
 details.
 
@@ -257,7 +263,7 @@ Boolean
 Probabilistic
   **body:**, **to:**, **attachment:**, **mimetype:**
 Special
-   **from:**, **query:**, **subject:**
+   **from:**, **query:**, **subject:**, **sexp:**
 
 Terms and phrases
 -----------------
@@ -275,11 +281,13 @@ the same phrase.
 - a.list.of.words
 
 Both parenthesised lists of terms and quoted phrases are ok with
-probabilistic prefixes such as **to:**, **from:**, and **subject:**. In particular
+probabilistic prefixes such as **to:**, **from:**, and **subject:**.
+For prefixes supporting regex search, the parenthesised list should be
+quoted.  In particular
 
 ::
 
-   subject:(pizza free)
+   subject:"(pizza free)"
 
 is equivalent to
 
@@ -295,6 +303,8 @@ Both of these will match a subject "Free Delicious Pizza" while
 
 will not.
 
+.. _quoting:
+
 Quoting
 -------
 
@@ -322,6 +332,13 @@ e.g.
    % notmuch search 'folder:"/^.*/(Junk|Spam)$/"'
    % notmuch search 'thread:"{from:mallory and date:2009}" and thread:{to:mallory}'
 
+Double quotes within query strings need to be doubled to escape them.
+
+::
+
+   % notmuch search 'tag:"""quoted tag"""'
+   % notmuch search 'sexp:"(or ""wizard"" ""php"")"'
+
 DATE AND TIME SEARCH
 ====================
 
diff --git a/doc/notmuch-emacs.rst b/doc/notmuch-emacs.rst
index 85b2c0ea..41f62390 100644
--- a/doc/notmuch-emacs.rst
+++ b/doc/notmuch-emacs.rst
@@ -331,11 +331,21 @@ tags.
 As is the case with :ref:`notmuch-search`, the presentation of results
 can be controlled by the variable ``notmuch-search-oldest-first``.
 
+.. _notmuch-unthreaded:
+
+notmuch-unthreaded
+------------------
+
+``notmuch-unthreaded-mode`` is similar to :any:`notmuch-tree` in that
+each line corresponds to a single message, but no thread information
+is presented.
+
+Keybindings are the same as :any:`notmuch-tree`.
 
 Global key bindings
 ===================
 
-Several features are accessible from anywhere in notmuch through the
+Several features are accessible from most places in notmuch through the
 following key bindings:
 
 ``j``
@@ -344,6 +354,8 @@ following key bindings:
 ``k``
     Tagging operations using :ref:`notmuch-tag-jump`
 
+``C-_`` ``C-/`` ``C-x u``: Undo previous tagging operation using :ref:`notmuch-tag-undo`
+
 .. _notmuch-jump:
 
 notmuch-jump
@@ -373,6 +385,21 @@ operations specified in ``notmuch-tagging-keys``; i.e. each
 
   |docstring::notmuch-tagging-keys|
 
+.. _notmuch-tag-undo:
+
+notmuch-tag-undo
+----------------
+
+Each notmuch buffer supporting tagging operations (i.e buffers in
+:any:`notmuch-show`, :any:`notmuch-search`, :any:`notmuch-tree`, and
+:any:`notmuch-unthreaded` mode) keeps a local stack of tagging
+operations. These can be undone via ``notmuch-tag-undo``. By default
+this is bound to the usual Emacs keys for undo.
+
+:index:`notmuch-tag-undo`
+
+   |docstring::notmuch-tag-undo|
+
 Buffer navigation
 =================