X-Git-Url: https://git.cworth.org/git?a=blobdiff_plain;f=doc%2Fnotmuch-emacs.rst;h=189a51ad96f47552ffed0a27ec99677a9da84d98;hb=cef5eaaef61b1f4dde6276ef267fb923f1b16680;hp=be7e324d41ad2bc14242cbdacafe3b614236367a;hpb=bde8ea5d1d92be15c6fb4c06e31d4fae750a12f0;p=notmuch diff --git a/doc/notmuch-emacs.rst b/doc/notmuch-emacs.rst index be7e324d..189a51ad 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 ================= @@ -48,16 +50,20 @@ a mouse or by positioning the cursor and pressing ```` 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: @@ -88,6 +94,9 @@ customizing the variables - 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 -------------------------- @@ -135,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 ---------- @@ -162,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: @@ -207,20 +218,24 @@ 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` +.. 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: -: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| @@ -266,27 +281,21 @@ pressing RET after positioning the cursor on a hidden part. ``?`` 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. @@ -307,6 +316,39 @@ Display of messages can be controlled by the following variables (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 @@ -453,7 +495,7 @@ 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| @@ -465,17 +507,18 @@ 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 +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 @@ -486,23 +529,25 @@ 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