X-Git-Url: https://git.cworth.org/git?a=blobdiff_plain;f=doc%2Fnotmuch-emacs.rst;h=162f62a4c7b2197c2bc28a35c329ed3818cf5571;hb=fe3db23684c9de5b879733b7c7e3f7bbffbee026;hp=22aee340c62061e31a582c3110468a019a6098d3;hpb=3eb25c94bd8fe4065d6df6d665ee393cb9a0ad6f;p=notmuch diff --git a/doc/notmuch-emacs.rst b/doc/notmuch-emacs.rst index 22aee340..162f62a4 100644 --- a/doc/notmuch-emacs.rst +++ b/doc/notmuch-emacs.rst @@ -1,6 +1,8 @@ -============= -notmuch-emacs -============= +.. _notmuch-emacs: + +========================== +Emacs Frontend for Notmuch +========================== About this Manual ================= @@ -46,9 +48,55 @@ a mouse or by positioning the cursor and pressing ```` | 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 + + A lower bound on the number of characters that will + be used to display each column. + + .. describe:: float + + 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`. + +.. emacsvar:: notmuch-show-empty-saved-searches + + |docstring::notmuch-show-empty-saved-searches| notmuch-hello key bindings -------------------------- @@ -96,25 +144,28 @@ The saved searches default to various common searches such as ``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 ---------- @@ -123,15 +174,14 @@ One special kind of saved search provided by default is for each 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: @@ -168,13 +218,60 @@ menu of results that the user can explore further by pressing 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: + +.. 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 @@ -211,17 +308,80 @@ pressing RET after positioning the cursor on a hidden part. ``+,-`` 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 @@ -271,6 +431,31 @@ in :ref:`notmuch-search`. ``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 (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 @@ -318,11 +503,63 @@ tags. 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 +------------------ + +``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`. + +.. 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 =================== -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`` @@ -331,6 +568,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 @@ -356,14 +595,30 @@ prefix (:kbd:`C-u k`), notmuch displays a menu of the reverses of the 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 @@ -374,22 +629,33 @@ 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`. +.. 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 ---------