-=============
-notmuch-emacs
-=============
+.. _notmuch-emacs:
+
+==========================
+Emacs Frontend for Notmuch
+==========================
About this Manual
=================
You can change the overall appearance of the notmuch-hello screen by
customizing the variables
-:index:`notmuch-hello-sections`
+.. emacsvar:: notmuch-hello-sections
+
|docstring::notmuch-hello-sections|
-:index:`notmuch-hello-thousands-separator`
+.. emacsvar:: notmuch-hello-thousands-separator
+
|docstring::notmuch-hello-thousands-separator|
-:index:`notmuch-show-logo`
+.. emacsvar:: notmuch-show-logo
+
|docstring::notmuch-show-logo|
-:index:`!notmuch-column-control`
+.. emacsvar:: notmuch-column-control
+
Controls the number of columns for saved searches/tags in notmuch view.
This variable has three potential types of values:
- if you don't want to worry about all of this nonsense, leave
this set to `t`.
+.. emacsvar:: notmuch-show-empty-saved-searches
+
+ |docstring::notmuch-show-empty-saved-searches|
notmuch-hello key bindings
--------------------------
``tag:inbox`` to access the inbox and ``tag:unread`` to access all
unread mail, but there are several options for customization:
-:index:`notmuch-saved-searches`
+.. emacsvar:: notmuch-saved-searches
+
The list of saved searches, including names, queries, and
additional per-query options.
-:index:`notmuch-saved-search-sort-function`
+.. emacsvar:: notmuch-saved-search-sort-function
+
This variable controls how saved searches should be sorted. A value
of ``nil`` displays the saved searches in the order they are stored
in ‘notmuch-saved-searches’.
-:index:`notmuch-column-control`
- Controls the number of columns for displaying saved-searches/tags
-
Search Box
----------
The search box lets the user enter a Notmuch query. See section
“Description” in Notmuch Query Syntax, for more info on Notmuch query
syntax. A history of recent searches is also displayed by default. The
-latter is controlled by the variable :index:`notmuch-hello-recent-searches-max`.
+latter is controlled by the variable `notmuch-hello-recent-searches-max`.
+
+.. emacsvar:: notmuch-hello-recent-searches-max
+
+ |docstring::notmuch-hello-recent-searches-max|
Known Tags
----------
individual tag defined in the database. This can be controlled via the
following variables.
-:index:`notmuch-hello-tag-list-make-query`
+.. emacsvar:: notmuch-hello-tag-list-make-query
+
Control how to construct a search (“virtual folder”) from a given
tag.
-:index:`notmuch-hello-hide-tags`
- Which tags not to display at all.
+.. emacsvar:: notmuch-hello-hide-tags
-:index:`notmuch-column-control`
- Controls the number of columns for displaying saved-searches/tags
+ Which tags not to display at all.
.. _notmuch-search:
The presentation of results can be controlled by the following
variables.
-:index:`notmuch-search-result-format`
- Control how each thread of messages is presented in the
- ``notmuch-show-mode`` buffer
+.. emacsvar:: notmuch-search-result-format
+
+ |docstring::notmuch-search-result-format|
+
+ If the car of an element in notmuch-search-result-format is a
+ function, insert the result of calling the function into the buffer.
+
+ This allows a user to generate custom fields in the output of a
+ search result. For example, with the following settings, the first
+ few characters on each line of the search result are used to show
+ information about some significant tags associated with the thread.
+
+ .. code:: lisp
+
+ (defun -notmuch-result-flags (format-string result)
+ (let ((tags-to-letters '(("flagged" . "!")
+ ("unread" . "u")
+ ("mine" . "m")
+ ("sent" . "s")
+ ("replied" . "r")))
+ (tags (plist-get result :tags)))
+ (format format-string
+ (mapconcat (lambda (t2l)
+ (if (member (car t2l) tags)
+ (cdr t2l)
+ " "))
+ tags-to-letters ""))))
+
+ (setq notmuch-search-result-format '((-notmuch-result-flags . "%s ")
+ ("date" . "%12s ")
+ ("count" . "%9s ")
+ ("authors" . "%-30s ")
+ ("subject" . "%s ")
+ ("tags" . "(%s)")))
+
+ See also :emacsvar:`notmuch-tree-result-format` and
+ :emacsvar:`notmuch-unthreaded-result-format`.
+
+.. emacsvar:: notmuch-search-oldest-first
-:index:`notmuch-search-oldest-first`
Display the oldest threads at the top of the buffer
It is also possible to customize how the name of buffers containing
search results is formatted using the following variables:
-:index:`notmuch-search-buffer-name-format`
+.. emacsvar:: notmuch-search-buffer-name-format
+
|docstring::notmuch-search-buffer-name-format|
-:index:`notmuch-saved-search-buffer-name-format`
+.. emacsvar:: notmuch-saved-search-buffer-name-format
+
|docstring::notmuch-saved-search-buffer-name-format|
``?``
Display full set of key bindings
-Display of messages can be controlled by the following variables
+Display of messages can be controlled by the following variables; see also :ref:`show-large`.
-:index:`notmuch-message-headers`
- |docstring::notmuch-message-headers|
+.. emacsvar:: notmuch-message-headers
-:index:`notmuch-message-headers-visible`
- |docstring::notmuch-message-headers-visible|
+ |docstring::notmuch-message-headers|
-:index:`notmuch-show-header-line`
- |docstring::notmuch-show-header-line|
+.. emacsvar:: notmuch-message-headers-visible
-:index:`notmuch-show-depth-limit`
- |docstring::notmuch-show-depth-limit|
+ |docstring::notmuch-message-headers-visible|
-:index:`notmuch-show-height-limit`
- |docstring::notmuch-show-height-limit|
+.. emacsvar:: notmuch-show-header-line
-:index:`notmuch-show-max-text-part-size`
- |docstring::notmuch-show-max-text-part-size|
+ |docstring::notmuch-show-header-line|
-:index:`notmuch-multipart/alternative-discouraged`
+.. emacsvar:: notmuch-multipart/alternative-discouraged
Which mime types to hide by default for multipart messages.
(t
(list "text/html" "multipart/related")))))
+.. _show-large:
+
+Dealing with large messages and threads
+---------------------------------------
+
+If you are finding :ref:`notmuch-show` is annoyingly slow displaying
+large messages, you can customize
+:emacsvar:`notmuch-show-max-text-part-size`. If you want to speed up the
+display of large threads (with or without large messages), there are
+several options. First, you can display the same query in one of the
+other modes. :ref:`notmuch-unthreaded` is the most robust for
+extremely large queries, but :ref:`notmuch-tree` is also be faster
+than :ref:`notmuch-show` in general, since it only renders a single
+message a time. If you prefer to stay with the rendered thread
+("conversation") view of :ref:`notmuch-show`, you can customize the
+variables :emacsvar:`notmuch-show-depth-limit`,
+:emacsvar:`notmuch-show-height-limit` and
+:emacsvar:`notmuch-show-max-text-part-size` to limit the amount of
+rendering done initially. Note that these limits are implicitly
+*OR*-ed together, and combinations might have surprising effects.
+
+.. emacsvar:: notmuch-show-depth-limit
+
+ |docstring::notmuch-show-depth-limit|
+
+.. emacsvar:: notmuch-show-height-limit
+
+ |docstring::notmuch-show-height-limit|
+
+.. emacsvar:: notmuch-show-max-text-part-size
+
+ |docstring::notmuch-show-max-text-part-size|
+
.. _show-copy:
Copy to kill-ring
``c ?``
Show all available copying commands
+.. _emacs-show-duplicates:
+
+Dealing with duplicates
+-----------------------
+
+If there are are multiple files with the same :mailheader:`Message-ID`
+(see :any:`duplicate-files`), then :any:`notmuch-show` displays the
+number of duplicates and identifies the current duplicate. In the
+following example duplicate 3 of 5 is displayed.
+
+.. code-block::
+ :emphasize-lines: 1
+
+ M. Mustermann <max@example.com> (Sat, 30 Jul 2022 10:33:10 -0300) (inbox signed) 3/5
+ Subject: Re: Multiple files per message in emacs
+ To: notmuch@notmuchmail.org
+
+To display a different message file with the same
+:mailheader:`Message-ID`, the user can run the command
+:emacscmd:`notmuch-show-choose-duplicate`, by default bound to `%`.
+
+.. emacscmd:: notmuch-show-choose-duplicate
+
+ |docstring::notmuch-show-choose-duplicate|
+
.. _notmuch-tree:
notmuch-tree
As is the case with :ref:`notmuch-search`, the presentation of results
can be controlled by the variable ``notmuch-search-oldest-first``.
+.. emacsvar:: notmuch-tree-result-format
+
+ |docstring::notmuch-tree-result-format|
+
+ The following example shows how to optionally display recipients instead
+ of authors for sent mail (assuming the user is named Mustermann).
+
+ .. code:: lisp
+
+ (defun -notmuch-authors-or-to (format-string result)
+ (let* ((headers (plist-get result :headers))
+ (to (plist-get headers :To))
+ (author (plist-get headers :From))
+ (face (if (plist-get result :match)
+ 'notmuch-tree-match-author-face
+ 'notmuch-tree-no-match-author-face)))
+ (propertize
+ (format format-string
+ (if (string-match "Mustermann" author)
+ (concat "To:" (notmuch-tree-clean-address to))
+ author))
+ 'face face)))
+
+ (setq notmuch-tree-result-format
+ '(("date" . "%12s ")
+ (-notmuch-authors-or-to . "%-20.20s")
+ ((("tree" . "%s")
+ ("subject" . "%s"))
+ . " %-54s ")
+ ("tags" . "(%s)")))
+
+ See also :emacsvar:`notmuch-search-result-format` and
+ :emacsvar:`notmuch-unthreaded-result-format`.
+
+
.. _notmuch-unthreaded:
notmuch-unthreaded
Keybindings are the same as :any:`notmuch-tree`.
+.. emacsvar:: notmuch-unthreaded-result-format
+
+ |docstring::notmuch-unthreaded-result-format|
+
+ See also :emacsvar:`notmuch-search-result-format` and
+ :emacsvar:`notmuch-tree-result-format`.
+
Global key bindings
===================
operations specified in ``notmuch-tagging-keys``; i.e. each
``+tag`` is replaced by ``-tag`` and vice versa.
-:index:`notmuch-tagging-keys`
+.. emacsvar:: notmuch-tagging-keys
|docstring::notmuch-tagging-keys|
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
+operations. These can be undone via :emacscmd:`notmuch-tag-undo`. By default
this is bound to the usual Emacs keys for undo.
-:index:`notmuch-tag-undo`
+.. emacscmd:: notmuch-tag-undo
|docstring::notmuch-tag-undo|
Buffer navigation
=================
-:index:`notmuch-cycle-notmuch-buffers`
+.. emacscmd:: notmuch-cycle-notmuch-buffers
+
|docstring::notmuch-cycle-notmuch-buffers|
Configuration
Importing Mail
--------------
-:index:`notmuch-poll`
+.. emacscmd:: notmuch-poll
+
|docstring::notmuch-poll|
-:index:`notmuch-poll-script`
+.. emacsvar:: notmuch-poll-script
+
|docstring::notmuch-poll-script|
Sending Mail
------------
-:index:`mail-user-agent`
+.. emacsvar:: mail-user-agent
Emacs consults the variable :code:`mail-user-agent` to choose a mail
sending package for commands like :code:`report-emacs-bug` and
:code:`compose-mail`. To use ``notmuch`` for this, customize this
variable to the symbol :code:`notmuch-user-agent`.
-:index:`message-dont-reply-to-names`
+.. emacsvar:: message-dont-reply-to-names
When composing mail replies, Emacs's message mode uses the
variable :code:`message-dont-reply-to-names` to exclude
projects / notmuch / blobdiff