X-Git-Url: https://git.cworth.org/git?p=notmuch;a=blobdiff_plain;f=doc%2Fnotmuch-emacs.rst;h=785287858d24cca3bbf9fe62a16bb9a2fd267361;hp=d68542d349a017b1fd6acb2bfd7400a38385bd41;hb=ae1fc657efa7e6dcbcbd79a3fe721e8f5b1f70a9;hpb=07dff496304d6dc2e8033a18691b095ed9cd212f diff --git a/doc/notmuch-emacs.rst b/doc/notmuch-emacs.rst index d68542d3..78528785 100644 --- a/doc/notmuch-emacs.rst +++ b/doc/notmuch-emacs.rst @@ -46,8 +46,47 @@ 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 +:index:`notmuch-hello-sections` + |docstring::notmuch-hello-sections| + +:index:`notmuch-hello-thousands-separator` + |docstring::notmuch-hello-thousands-separator| + +:index:`notmuch-show-logo` + |docstring::notmuch-show-logo| + +:index:`!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`. notmuch-hello key bindings @@ -56,13 +95,13 @@ notmuch-hello key bindings ```` Move to the next widget (button or text entry field) -```` +```` Move to the previous widget. ```` Activate the current widget. -``=`` +``g`` ``=`` Refresh the buffer; mainly update the counts of messages for various saved searches. @@ -100,7 +139,7 @@ unread mail, but there are several options for customization: The list of saved searches, including names, queries, and additional per-query options. -:index:`notmuch-saved-searches-sort-function` +:index:`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’. @@ -159,6 +198,9 @@ menu of results that the user can explore further by pressing ```` Open thread on current line in :ref:`notmuch-show` mode +``g`` ``=`` + Refresh the buffer + ``?`` Display full set of key bindings @@ -172,27 +214,217 @@ variables. :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` + |docstring::notmuch-search-buffer-name-format| + +:index:`notmuch-saved-search-buffer-name-format` + |docstring::notmuch-saved-search-buffer-name-format| + + .. _notmuch-show: notmuch-show ============ +``notmuch-show-mode`` is used to display a single thread of email from +your email archives. + +By default, various components of email messages, (citations, +signatures, already-read messages), are hidden. You can make +these parts visible by clicking with the mouse button or by +pressing RET after positioning the cursor on a hidden part. + +```` + Scroll the current message (if necessary), + advance to the next message, or advance to the next thread (if + already on the last message of a thread). + +``c`` + :ref:`show-copy` + +``N`` + Move to next message + +``P`` + Move to previous message (or start of current message) + +``n`` + Move to next matching message + +``p`` + Move to previous matching message + +``+,-`` + 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 + +:index:`notmuch-message-headers` + |docstring::notmuch-message-headers| + +:index:`notmuch-message-headers-visible` + |docstring::notmuch-message-headers-visible| + +:index:`notmuch-show-header-line` + |docstring::notmuch-show-header-line| + +:index:`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-copy: + +Copy to kill-ring +----------------- + +You can use the usually Emacs ways of copying text to the kill-ring, +but notmuch also provides some shortcuts. These keys are available in +:ref:`notmuch-show`, and :ref:`notmuch-tree`. A subset are available +in :ref:`notmuch-search`. + +``c F`` ``notmuch-show-stash-filename`` + |docstring::notmuch-show-stash-filename| + +``c G`` ``notmuch-show-stash-git-send-email`` + |docstring::notmuch-show-stash-git-send-email| + +``c I`` ``notmuch-show-stash-message-id-stripped`` + |docstring::notmuch-show-stash-message-id-stripped| + +``c L`` ``notmuch-show-stash-mlarchive-link-and-go`` + |docstring::notmuch-show-stash-mlarchive-link-and-go| + +``c T`` ``notmuch-show-stash-tags`` + |docstring::notmuch-show-stash-tags| + +``c c`` ``notmuch-show-stash-cc`` + |docstring::notmuch-show-stash-cc| + +``c d`` ``notmuch-show-stash-date`` + |docstring::notmuch-show-stash-date| + +``c f`` ``notmuch-show-stash-from`` + |docstring::notmuch-show-stash-from| + +``c i`` ``notmuch-show-stash-message-id`` + |docstring::notmuch-show-stash-message-id| + +``c l`` ``notmuch-show-stash-mlarchive-link`` + |docstring::notmuch-show-stash-mlarchive-link| + +``c s`` ``notmuch-show-stash-subject`` + |docstring::notmuch-show-stash-subject| + +``c t`` ``notmuch-show-stash-to`` + |docstring::notmuch-show-stash-to| + +``c ?`` + Show all available copying commands + +.. _notmuch-tree: + notmuch-tree ============ +``notmuch-tree-mode`` displays the results of a "notmuch tree" of your +email archives. Each line in the buffer represents a single +message giving the relative date, the author, subject, and any +tags. + +``c`` + :ref:`show-copy` + +```` + Displays that message. + +``N`` + Move to next message + +``P`` + Move to previous message + +``n`` + Move to next matching message + +``p`` + Move to previous matching message + +``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`` Jump to saved searches using :ref:`notmuch-jump`. +``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 ------------ -Saved searches configured through :ref:`notmuch-saved-searches` can +Saved searches configured through :ref:`saved-searches` can include a "shortcut key" that's accessible through notmuch-jump. Pressing ``j`` anywhere in notmuch followed by the configured shortcut key of a saved search will immediately jump to that saved search. For @@ -200,6 +432,43 @@ example, in the default configuration ``j i`` jumps immediately to the inbox search. When you press ``j``, notmuch-jump shows the saved searches and their shortcut keys in the mini-buffer. +.. _notmuch-tag-jump: + +notmuch-tag-jump +---------------- + +Tagging operations configured through ``notmuch-tagging-keys`` can +be accessed via :kbd:`k` in :ref:`notmuch-show`, +:ref:`notmuch-search` and :ref:`notmuch-tree`. With a +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` + + |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 +================= + +:index:`notmuch-cycle-notmuch-buffers` + |docstring::notmuch-cycle-notmuch-buffers| + Configuration ============= @@ -209,8 +478,20 @@ Importing Mail -------------- :index:`notmuch-poll` + |docstring::notmuch-poll| :index:`notmuch-poll-script` + |docstring::notmuch-poll-script| + +Sending Mail +------------ + +:index:`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`. Init File ---------