-=============
-notmuch-emacs
-=============
+.. _notmuch-emacs:
+
+==========================
+Emacs Frontend for Notmuch
+==========================
About this Manual
=================
| Customize Notmuch or this page.
You can change the overall appearance of the notmuch-hello screen by
-customizing the variable :index:`notmuch-hello-sections`.
+customizing the variables
+
+.. emacsvar:: notmuch-hello-sections
+
+ |docstring::notmuch-hello-sections|
+
+.. emacsvar:: notmuch-hello-thousands-separator
+
+ |docstring::notmuch-hello-thousands-separator|
+
+.. emacsvar:: notmuch-show-logo
+
+ |docstring::notmuch-show-logo|
+
+.. emacsvar:: notmuch-column-control
+
+ Controls the number of columns for saved searches/tags in notmuch view.
+
+ This variable has three potential types of values:
+
+ .. describe:: t
+
+ Automatically calculate the number of columns possible based
+ on the tags to be shown and the window width.
+
+ .. describe:: integer <n>
+
+ A lower bound on the number of characters that will
+ be used to display each column.
+
+ .. describe:: float <f>
+
+ A fraction of the window width that is the lower bound on the
+ number of characters that should be used for each column.
+
+ So:
+
+ - if you would like two columns of tags, set this to 0.5.
+
+ - if you would like a single column of tags, set this to 1.0.
+
+ - if you would like tags to be 30 characters wide, set this to 30.
+ - if you don't want to worry about all of this nonsense, leave
+ this set to `t`.
notmuch-hello key bindings
``<tab>``
Move to the next widget (button or text entry field)
-``<backspace>``
+``<backtab>``
Move to the previous widget.
``<return>``
Activate the current widget.
-``g``
-``=``
+``g`` ``=``
Refresh the buffer; mainly update the counts of messages for various
saved searches.
``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-searches-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:
``<return>``
Open thread on current line in :ref:`notmuch-show` mode
-``g``
-``=``
+``g`` ``=``
Refresh the buffer
``?``
The presentation of results can be controlled by the following
variables.
-:index:`notmuch-search-result-format`
+.. emacsvar:: notmuch-search-result-format
+
Control how each thread of messages is presented in the
``notmuch-show-mode`` buffer
-:index:`notmuch-search-oldest-first`
+.. emacsvar:: 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:
+
+.. emacsvar:: notmuch-search-buffer-name-format
+
+ |docstring::notmuch-search-buffer-name-format|
+
+.. emacsvar:: notmuch-saved-search-buffer-name-format
+
+ |docstring::notmuch-saved-search-buffer-name-format|
+
+
.. _notmuch-show:
notmuch-show
``+,-``
Add or remove arbitrary tags from the current message.
+``!``
+ |docstring::notmuch-show-toggle-elide-non-matching|
+
``?``
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`.
+
+.. emacsvar:: notmuch-message-headers
-:index:`notmuch-message-headers`
|docstring::notmuch-message-headers|
-:index:`notmuch-message-headers-visible`
+.. emacsvar:: notmuch-message-headers-visible
+
|docstring::notmuch-message-headers-visible|
+.. emacsvar:: notmuch-show-header-line
+
+ |docstring::notmuch-show-header-line|
+
+.. emacsvar:: notmuch-multipart/alternative-discouraged
+
+ Which mime types to hide by default for multipart messages.
+
+ Can either be a list of mime types (as strings) or a function
+ mapping a plist representing the current message to such a list.
+ The following example function would discourage `text/html` and
+ `multipart/related` generally, but discourage `text/plain` should
+ the message be sent from `whatever@example.com`.
+
+ .. code:: lisp
+
+ (defun my--determine-discouraged (msg)
+ (let* ((headers (plist-get msg :headers))
+ (from (or (plist-get headers :From) "")))
+ (cond
+ ((string-match "whatever@example.com" from)
+ (list "text/plain"))
+ (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
``p``
Move to previous matching message
-``g``
-``=``
+``o`` ``notmuch-tree-toggle-order``
+ |docstring::notmuch-tree-toggle-order|
+
+``l`` ``notmuch-tree-filter``
+ Filter or LIMIT the current search results based on an additional query string
+
+``t`` ``notmuch-tree-filter-by-tag``
+ Filter the current search results based on an additional tag
+
+
+``g`` ``=``
Refresh the buffer
``?``
Display full set of key bindings
+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``
``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
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|
+.. _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 :emacscmd:`notmuch-tag-undo`. By default
+this is bound to the usual Emacs keys for 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
+------------
+
+.. 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`.
+
+.. 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
+ recipients matching a given collection of regular expressions
+ or satisfying an arbitrary predicate. Notmuch's MUA inherits
+ this standard mechanism and will honour your customization of
+ this variable.
+
Init File
---------
order). Most often users create ``~/.emacs.d/notmuch-config.el`` and just
work with it. If Emacs was invoked with the ``-q`` or ``--no-init-file``
options, ``notmuch-init-file`` is not read.
-
-.. include:: ../emacs/rstdoc.rsti
-
-.. include:: ../emacs/notmuch.rsti
-
-.. include:: ../emacs/notmuch-lib.rsti
-
-.. include:: ../emacs/notmuch-show.rsti
-
-.. include:: ../emacs/notmuch-tag.rsti