debian/notmuch
1
0
Fork 0
mirror of https://git.notmuchmail.org/git/notmuch synced 2024-11-26 20:57:58 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions
notmuch/doc/notmuch-emacs.rst

793 lines
22 KiB
ReStructuredText
Raw Permalink Normal View History

doc: retitle notmuch-emacs manual This makes the HTML TOC read more naturally. Add a label to make cross referencing easier.
2022-06-30 14:27:10 +02:00
.. _notmuch-emacs:
==========================
Emacs Frontend for Notmuch
==========================
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
About this Manual
=================
doc: added 'Init File' section to notmuch-emacs info source While adding that fixed (also other) typos noticed by aspell(1) run, and capitalized Emacs and (most) Notmuch terms to match how emacs Info documentation seems to look in general.
2014-04-03 22:53:03 +02:00
This manual covers only the Emacs interface to Notmuch. For information
doc: Emacs manual improvements and expansions Fix several typos, improve general wording and flow, and add some information on notmuch-jump.
2014-10-03 16:27:26 +02:00
on the command line interface, see section “Description” in the Notmuch
Manual Pages. To save typing, we will sometimes use *notmuch* in this
manual to refer to the Emacs interface to Notmuch. When this distinction
is important, we’ll refer to the Emacs interface as
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
*notmuch-emacs*.
doc: fix typos
2023-04-13 15:52:11 +02:00
Notmuch-emacs is highly customizable via the Emacs customization
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
framework (or just by setting the appropriate variables). We try to
point out relevant variables in this manual, but in order to avoid
doc: Emacs manual improvements and expansions Fix several typos, improve general wording and flow, and add some information on notmuch-jump.
2014-10-03 16:27:26 +02:00
duplication of information, you can usually find the most detailed
description in the variables' docstring.
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
notmuch-hello
=============
.. index::
single: notmuch-hello
single: notmuch
doc: added 'Init File' section to notmuch-emacs info source While adding that fixed (also other) typos noticed by aspell(1) run, and capitalized Emacs and (most) Notmuch terms to match how emacs Info documentation seems to look in general.
2014-04-03 22:53:03 +02:00
``notmuch-hello`` is the main entry point for Notmuch. You can start it
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
with ``M-x notmuch`` or ``M-x notmuch-hello``. The startup screen looks
something like the following. There are some hints at the bottom of the
screen. There are three main parts to the notmuch-hello screen,
discussed below. The **bold** text indicates buttons you can click with
a mouse or by positioning the cursor and pressing ``<return>``
| Welcome to **notmuch** You have 52 messages.
|
| Saved searches: **[edit]**
|
| 52 **inbox** 52 **unread**
|
| Search: ____________________________________
|
| All tags: **[show]**
|
doc/notmuch-emacs.rst: update notmuch-hello buffer help text To look the same as commit b8a136187a3b changed it in emacs MUA code.
2016-06-05 22:38:05 +02:00
| Hit \`?' for context-sensitive help in any Notmuch screen.
| Customize Notmuch or this page.
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
doc: added 'Init File' section to notmuch-emacs info source While adding that fixed (also other) typos noticed by aspell(1) run, and capitalized Emacs and (most) Notmuch terms to match how emacs Info documentation seems to look in general.
2014-04-03 22:53:03 +02:00
You can change the overall appearance of the notmuch-hello screen by
doc/emacs: document a few notmuch-hello customizable variables. A user asked about the thousands separator on IRC, and I had to check the source.
2022-05-16 12:46:10 +02:00
customizing the variables
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
doc/emacs: replace use of emacsvar with el:defcustom Mainly this allows dropping the ad-hoc directive emacsvar
2022-07-31 13:33:22 +02:00
.. el:defcustom:: notmuch-hello-sections
doc/emacs: define and use emacsvar and emacscmd markup This makes it easier to navigate the merged index of all of the notmuch documentation.
2022-07-01 12:40:39 +02:00
doc/emacs: document a few notmuch-hello customizable variables. A user asked about the thousands separator on IRC, and I had to check the source.
2022-05-16 12:46:10 +02:00
|docstring::notmuch-hello-sections|
doc/emacs: replace use of emacsvar with el:defcustom Mainly this allows dropping the ad-hoc directive emacsvar
2022-07-31 13:33:22 +02:00
.. el:defcustom:: notmuch-hello-thousands-separator
doc/emacs: define and use emacsvar and emacscmd markup This makes it easier to navigate the merged index of all of the notmuch documentation.
2022-07-01 12:40:39 +02:00
doc/emacs: document a few notmuch-hello customizable variables. A user asked about the thousands separator on IRC, and I had to check the source.
2022-05-16 12:46:10 +02:00
|docstring::notmuch-hello-thousands-separator|
doc/emacs: replace use of emacsvar with el:defcustom Mainly this allows dropping the ad-hoc directive emacsvar
2022-07-31 13:33:22 +02:00
.. el:defcustom:: notmuch-show-logo
doc/emacs: define and use emacsvar and emacscmd markup This makes it easier to navigate the merged index of all of the notmuch documentation.
2022-07-01 12:40:39 +02:00
doc/emacs: document a few notmuch-hello customizable variables. A user asked about the thousands separator on IRC, and I had to check the source.
2022-05-16 12:46:10 +02:00
|docstring::notmuch-show-logo|
doc/emacs: replace use of emacsvar with el:defcustom Mainly this allows dropping the ad-hoc directive emacsvar
2022-07-31 13:33:22 +02:00
.. el:defcustom:: notmuch-column-control
doc/emacs: define and use emacsvar and emacscmd markup This makes it easier to navigate the merged index of all of the notmuch documentation.
2022-07-01 12:40:39 +02:00
doc/emacs: document a few notmuch-hello customizable variables. A user asked about the thousands separator on IRC, and I had to check the source.
2022-05-16 12:46:10 +02:00
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`.
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
doc/emacs: replace use of emacsvar with el:defcustom Mainly this allows dropping the ad-hoc directive emacsvar
2022-07-31 13:33:22 +02:00
.. el:defcustom:: notmuch-show-empty-saved-searches
doc/emacs: add notmuch-show-empty-saved-searches to manual Answering a user question, I had to dig for this variable, but I think it is a reasonably common customization wish, particularly for users with custom count-functions.
2022-07-01 18:14:29 +02:00
|docstring::notmuch-show-empty-saved-searches|
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
notmuch-hello key bindings
--------------------------
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: <tab>
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
Move to the next widget (button or text entry field)
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: <backtab>
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
Move to the previous widget.
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: <return>
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
Activate the current widget.
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: g
=
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
Refresh the buffer; mainly update the counts of messages for various
saved searches.
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: G
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
Import mail, See :ref:`importing`
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: m
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
Compose a message
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: s
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
Search the notmuch database using :ref:`notmuch-search`
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: v
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
Print notmuch version
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: q
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
Quit
.. _saved-searches:
Saved Searches
--------------
doc: Emacs manual improvements and expansions Fix several typos, improve general wording and flow, and add some information on notmuch-jump.
2014-10-03 16:27:26 +02:00
Since notmuch is entirely search-based, it's often useful to organize
mail around common searches. To facilitate this, the first section of
notmuch-hello presents a customizable set of saved searches. Saved
searches can also be accessed from anywhere in notmuch by pressing
``j`` to access :ref:`notmuch-jump`.
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:
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
doc/emacs: replace use of emacsvar with el:defcustom Mainly this allows dropping the ad-hoc directive emacsvar
2022-07-31 13:33:22 +02:00
.. el:defcustom:: notmuch-saved-searches
doc/emacs: define and use emacsvar and emacscmd markup This makes it easier to navigate the merged index of all of the notmuch documentation.
2022-07-01 12:40:39 +02:00
doc: Emacs manual improvements and expansions Fix several typos, improve general wording and flow, and add some information on notmuch-jump.
2014-10-03 16:27:26 +02:00
The list of saved searches, including names, queries, and
additional per-query options.
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
doc/emacs: replace use of emacsvar with el:defcustom Mainly this allows dropping the ad-hoc directive emacsvar
2022-07-31 13:33:22 +02:00
.. el:defcustom:: notmuch-saved-search-sort-function
doc/emacs: define and use emacsvar and emacscmd markup This makes it easier to navigate the merged index of all of the notmuch documentation.
2022-07-01 12:40:39 +02:00
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
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’.
Search Box
----------
doc: added 'Init File' section to notmuch-emacs info source While adding that fixed (also other) typos noticed by aspell(1) run, and capitalized Emacs and (most) Notmuch terms to match how emacs Info documentation seems to look in general.
2014-04-03 22:53:03 +02:00
The search box lets the user enter a Notmuch query. See section
“Description” in Notmuch Query Syntax, for more info on Notmuch query
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
syntax. A history of recent searches is also displayed by default. The
doc/emacs: define and use emacsvar and emacscmd markup This makes it easier to navigate the merged index of all of the notmuch documentation.
2022-07-01 12:40:39 +02:00
latter is controlled by the variable `notmuch-hello-recent-searches-max`.
doc/emacs: replace use of emacsvar with el:defcustom Mainly this allows dropping the ad-hoc directive emacsvar
2022-07-31 13:33:22 +02:00
.. el:defcustom:: notmuch-hello-recent-searches-max
doc/emacs: define and use emacsvar and emacscmd markup This makes it easier to navigate the merged index of all of the notmuch documentation.
2022-07-01 12:40:39 +02:00
|docstring::notmuch-hello-recent-searches-max|
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
Known Tags
----------
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.
doc/emacs: replace use of emacsvar with el:defcustom Mainly this allows dropping the ad-hoc directive emacsvar
2022-07-31 13:33:22 +02:00
.. el:defcustom:: notmuch-hello-tag-list-make-query
doc/emacs: define and use emacsvar and emacscmd markup This makes it easier to navigate the merged index of all of the notmuch documentation.
2022-07-01 12:40:39 +02:00
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
Control how to construct a search (“virtual folder”) from a given
tag.
doc/emacs: replace use of emacsvar with el:defcustom Mainly this allows dropping the ad-hoc directive emacsvar
2022-07-31 13:33:22 +02:00
.. el:defcustom:: notmuch-hello-hide-tags
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
doc/emacs: define and use emacsvar and emacscmd markup This makes it easier to navigate the merged index of all of the notmuch documentation.
2022-07-01 12:40:39 +02:00
Which tags not to display at all.
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
.. _notmuch-search:
notmuch-search
==============
``notmuch-search-mode`` is used to display the results from executing
a query via ``notmuch-search``. The syntax for these queries is the
the same as :ref:`saved-searches`. For details of this syntax see
info:notmuch-search-terms
By default the output approximates that of the command line See section
“Description” in notmuch search command.
The main purpose of the ``notmuch-search-mode`` buffer is to act as a
menu of results that the user can explore further by pressing
``<return>`` on the appropriate line.
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: n
C-n
<down>
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
Move to next line
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key::
p
C-p
<up>
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
Move to previous line
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: <return>
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
Open thread on current line in :ref:`notmuch-show` mode
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: g
=
Emacs: bind "g" to 'notuch-refresh-this-buffer Using "g" for refresh operations is a pretty common Emacs convention, codified by `special-mode' in simple.el.
2019-02-16 21:27:30 +01:00
Refresh the buffer
emacs: Add new option notmuch-search-hide-excluded The new notmuch-search-hide-excluded option allows users to configure whether to show or hide excluded messages (as determined by search.exclude_tags in the local notmuch config file). It defaults to true for now to maintain backwards-compatibility with how notmuch-{search,tree} already worked. New commands notmuch-search-toggle-hide-excluded and notmuch-tree-toggle-exclude have also been added. They toggle the value of notmuch-search-hide-excluded for the search in the current search or tree buffer. It's bound to "i" in the respective keymaps for these modes. Lastly I've amended some calls to notmuch-tree and notmuch-unthreaded which didn't pass through the buffer local value of notmuch-search-oldest-first (and now notmuch-search-exclude). Examples of where I've done this include: + notmuch-jump-search + notmuch-tree-from-search-current-query + notmuch-unthreaded-from-search-current-query + notmuch-tree-from-search-thread A new test file for Emacs has been added which covers the usage of the new `notmuch-search-hide-excluded' option and interactively hiding or showing mail with excluded tags. These test cover the basic usage of the `notmuch-search-toggle-hide-excluded' command in notmuch-search, notmuch-tree and notmuch-unthreaded searches. These tests also cover the persistence of the current value of the hide-excluded mail option as a user switches from between these different search commands. [1]: id:87ilxlxsng.fsf@kisara.moe Amended-by: db, fix indentation in T461-emacs-search-exclude.sh
2024-03-10 19:57:41 +01:00
.. el:define-key:: i
Toggle whether to show messages with excluded tags in search results.
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: ?
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
Display full set of key bindings
The presentation of results can be controlled by the following
variables.
doc/emacs: replace use of emacsvar with el:defcustom Mainly this allows dropping the ad-hoc directive emacsvar
2022-07-31 13:33:22 +02:00
.. el:defcustom:: notmuch-search-result-format
doc/emacs: define and use emacsvar and emacscmd markup This makes it easier to navigate the merged index of all of the notmuch documentation.
2022-07-01 12:40:39 +02:00
doc/emacs: add docstring and example for n-search-result-format When the ability to use functions was added, this example was confined to a commit message, which is not user discoverable.
2022-07-16 23:22:24 +02:00
|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)")))
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
doc/emacs: replace use of emacsvar with el:defcustom Mainly this allows dropping the ad-hoc directive emacsvar
2022-07-31 13:33:22 +02:00
See also :el:defcustom:`notmuch-tree-result-format` and
:el:defcustom:`notmuch-unthreaded-result-format`.
doc/emacs: add docstring and example for n-tree-result-format This example is based on one originally by Jon Hurst.
2022-07-16 23:22:26 +02:00
doc/emacs: replace use of emacsvar with el:defcustom Mainly this allows dropping the ad-hoc directive emacsvar
2022-07-31 13:33:22 +02:00
.. el:defcustom:: notmuch-search-oldest-first
doc/emacs: define and use emacsvar and emacscmd markup This makes it easier to navigate the merged index of all of the notmuch documentation.
2022-07-01 12:40:39 +02:00
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
Display the oldest threads at the top of the buffer
emacs: customizable names for search buffers Customizable names for buffers presenting search results, via two custom variables (notmuch-search-buffer-name-format and notmuch-saved-search-buffer-name-format), defaulting to values currently used for plain searches and including too tree and unthreaded search buffers. Amended by db: spelling fix.
2022-01-23 20:54:17 +01:00
It is also possible to customize how the name of buffers containing
search results is formatted using the following variables:
doc/emacs: replace use of emacsvar with el:defcustom Mainly this allows dropping the ad-hoc directive emacsvar
2022-07-31 13:33:22 +02:00
.. el:defcustom:: notmuch-search-buffer-name-format
doc/emacs: define and use emacsvar and emacscmd markup This makes it easier to navigate the merged index of all of the notmuch documentation.
2022-07-01 12:40:39 +02:00
emacs: customizable names for search buffers Customizable names for buffers presenting search results, via two custom variables (notmuch-search-buffer-name-format and notmuch-saved-search-buffer-name-format), defaulting to values currently used for plain searches and including too tree and unthreaded search buffers. Amended by db: spelling fix.
2022-01-23 20:54:17 +01:00
|docstring::notmuch-search-buffer-name-format|
doc/emacs: replace use of emacsvar with el:defcustom Mainly this allows dropping the ad-hoc directive emacsvar
2022-07-31 13:33:22 +02:00
.. el:defcustom:: notmuch-saved-search-buffer-name-format
doc/emacs: define and use emacsvar and emacscmd markup This makes it easier to navigate the merged index of all of the notmuch documentation.
2022-07-01 12:40:39 +02:00
emacs: customizable names for search buffers Customizable names for buffers presenting search results, via two custom variables (notmuch-search-buffer-name-format and notmuch-saved-search-buffer-name-format), defaulting to values currently used for plain searches and including too tree and unthreaded search buffers. Amended by db: spelling fix.
2022-01-23 20:54:17 +01:00
|docstring::notmuch-saved-search-buffer-name-format|
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
.. _notmuch-show:
notmuch-show
============
doc: initial documentation for notmuch-show-mode This is pretty minimal, but will hopefully inspire others to contribute more complete documentation. If nothing else, it points out '?'.
2018-05-21 22:08:54 +02:00
``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.
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: <space>
doc: initial documentation for notmuch-show-mode This is pretty minimal, but will hopefully inspire others to contribute more complete documentation. If nothing else, it points out '?'.
2018-05-21 22:08:54 +02:00
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).
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: c
doc/emacs: add documentation for stashing 'c X' bindings This is the first of a series of changes requiring the extracted docstrings.
2018-06-14 02:32:41 +02:00
:ref:`show-copy`
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: N
doc: initial documentation for notmuch-show-mode This is pretty minimal, but will hopefully inspire others to contribute more complete documentation. If nothing else, it points out '?'.
2018-05-21 22:08:54 +02:00
Move to next message
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: P
doc: initial documentation for notmuch-show-mode This is pretty minimal, but will hopefully inspire others to contribute more complete documentation. If nothing else, it points out '?'.
2018-05-21 22:08:54 +02:00
Move to previous message (or start of current message)
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: n
doc: initial documentation for notmuch-show-mode This is pretty minimal, but will hopefully inspire others to contribute more complete documentation. If nothing else, it points out '?'.
2018-05-21 22:08:54 +02:00
Move to next matching message
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: p
doc: initial documentation for notmuch-show-mode This is pretty minimal, but will hopefully inspire others to contribute more complete documentation. If nothing else, it points out '?'.
2018-05-21 22:08:54 +02:00
Move to previous matching message
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: +
-
doc: initial documentation for notmuch-show-mode This is pretty minimal, but will hopefully inspire others to contribute more complete documentation. If nothing else, it points out '?'.
2018-05-21 22:08:54 +02:00
Add or remove arbitrary tags from the current message.
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: !
doc/emacs: document notmuch-show-toggle-toggle-elide-non-matching Recently there was a question on the mailing list about the existence of this function, so let us try to make it more discoverable.
2022-05-12 12:47:52 +02:00
|docstring::notmuch-show-toggle-elide-non-matching|
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: ?
doc: initial documentation for notmuch-show-mode This is pretty minimal, but will hopefully inspire others to contribute more complete documentation. If nothing else, it points out '?'.
2018-05-21 22:08:54 +02:00
Display full set of key bindings
doc/emacs: add discussion about notmuch-show performance. Most of the information is already in the docstrings, but hopefully by grouping it is more discoverable.
2022-06-28 03:02:05 +02:00
Display of messages can be controlled by the following variables; see also :ref:`show-large`.
doc/emacs: document notmuch-message-headers* More precisely, copy the docstrings into notmuch-emacs documentation pages.
2018-06-14 02:32:42 +02:00
doc/emacs: replace use of emacsvar with el:defcustom Mainly this allows dropping the ad-hoc directive emacsvar
2022-07-31 13:33:22 +02:00
.. el:defcustom:: notmuch-message-headers
doc/emacs: define and use emacsvar and emacscmd markup This makes it easier to navigate the merged index of all of the notmuch documentation.
2022-07-01 12:40:39 +02:00
doc/emacs: document notmuch-message-headers* More precisely, copy the docstrings into notmuch-emacs documentation pages.
2018-06-14 02:32:42 +02:00
|docstring::notmuch-message-headers|
doc/emacs: replace use of emacsvar with el:defcustom Mainly this allows dropping the ad-hoc directive emacsvar
2022-07-31 13:33:22 +02:00
.. el:defcustom:: notmuch-message-headers-visible
doc/emacs: define and use emacsvar and emacscmd markup This makes it easier to navigate the merged index of all of the notmuch documentation.
2022-07-01 12:40:39 +02:00
doc/emacs: document notmuch-message-headers* More precisely, copy the docstrings into notmuch-emacs documentation pages.
2018-06-14 02:32:42 +02:00
|docstring::notmuch-message-headers-visible|
doc/emacs: replace use of emacsvar with el:defcustom Mainly this allows dropping the ad-hoc directive emacsvar
2022-07-31 13:33:22 +02:00
.. el:defcustom:: notmuch-show-header-line
doc/emacs: define and use emacsvar and emacscmd markup This makes it easier to navigate the merged index of all of the notmuch documentation.
2022-07-01 12:40:39 +02:00
emacs: make header line in notmuch-show buffers optional New notmuch-show-header-line customizable boolean to allow inhibiting a header line in notmuch-show-mode buffers (for instance, because one prefers to just include Subject in notmuch-message-headers).
2022-01-10 04:05:23 +01:00
|docstring::notmuch-show-header-line|
doc/emacs: replace use of emacsvar with el:defcustom Mainly this allows dropping the ad-hoc directive emacsvar
2022-07-31 13:33:22 +02:00
.. el:defcustom:: notmuch-multipart/alternative-discouraged
emacs: document/defcustom notmuch-multipart/alternative-discouraged This variable is important for people who want to change the default behaviour when displaying multipart/alternative messages. Previously it was undocumented. Add a defcustom to help users and copy some documentation from the wiki. The usual machinery of re-using docstrings is a bit tricky to use here because it mangles the example lisp code, and the link to the info node should not be in e.g. the html page. Add a simple test to make sure the switch from defvar to defcustom did not break something obvious.
2022-05-14 13:26:38 +02:00
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")))))
doc/emacs: add discussion about notmuch-show performance. Most of the information is already in the docstrings, but hopefully by grouping it is more discoverable.
2022-06-28 03:02:05 +02:00
.. _show-large:
Dealing with large messages and threads
---------------------------------------
If you are finding :ref:`notmuch-show` is annoyingly slow displaying
large messages, you can customize
doc/emacs: replace use of emacsvar with el:defcustom Mainly this allows dropping the ad-hoc directive emacsvar
2022-07-31 13:33:22 +02:00
:el:defcustom:`notmuch-show-max-text-part-size`. If you want to speed up the
doc/emacs: add discussion about notmuch-show performance. Most of the information is already in the docstrings, but hopefully by grouping it is more discoverable.
2022-06-28 03:02:05 +02:00
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
doc/emacs: replace use of emacsvar with el:defcustom Mainly this allows dropping the ad-hoc directive emacsvar
2022-07-31 13:33:22 +02:00
variables :el:defcustom:`notmuch-show-depth-limit`,
:el:defcustom:`notmuch-show-height-limit` and
:el:defcustom:`notmuch-show-max-text-part-size` to limit the amount of
doc/emacs: add discussion about notmuch-show performance. Most of the information is already in the docstrings, but hopefully by grouping it is more discoverable.
2022-06-28 03:02:05 +02:00
rendering done initially. Note that these limits are implicitly
*OR*-ed together, and combinations might have surprising effects.
doc/emacs: replace use of emacsvar with el:defcustom Mainly this allows dropping the ad-hoc directive emacsvar
2022-07-31 13:33:22 +02:00
.. el:defcustom:: notmuch-show-depth-limit
doc/emacs: define and use emacsvar and emacscmd markup This makes it easier to navigate the merged index of all of the notmuch documentation.
2022-07-01 12:40:39 +02:00
doc/emacs: add discussion about notmuch-show performance. Most of the information is already in the docstrings, but hopefully by grouping it is more discoverable.
2022-06-28 03:02:05 +02:00
|docstring::notmuch-show-depth-limit|
doc/emacs: replace use of emacsvar with el:defcustom Mainly this allows dropping the ad-hoc directive emacsvar
2022-07-31 13:33:22 +02:00
.. el:defcustom:: notmuch-show-height-limit
doc/emacs: define and use emacsvar and emacscmd markup This makes it easier to navigate the merged index of all of the notmuch documentation.
2022-07-01 12:40:39 +02:00
doc/emacs: add discussion about notmuch-show performance. Most of the information is already in the docstrings, but hopefully by grouping it is more discoverable.
2022-06-28 03:02:05 +02:00
|docstring::notmuch-show-height-limit|
doc/emacs: replace use of emacsvar with el:defcustom Mainly this allows dropping the ad-hoc directive emacsvar
2022-07-31 13:33:22 +02:00
.. el:defcustom:: notmuch-show-max-text-part-size
doc/emacs: define and use emacsvar and emacscmd markup This makes it easier to navigate the merged index of all of the notmuch documentation.
2022-07-01 12:40:39 +02:00
doc/emacs: add discussion about notmuch-show performance. Most of the information is already in the docstrings, but hopefully by grouping it is more discoverable.
2022-06-28 03:02:05 +02:00
|docstring::notmuch-show-max-text-part-size|
doc/emacs: add documentation for stashing 'c X' bindings This is the first of a series of changes requiring the extracted docstrings.
2018-06-14 02:32:41 +02:00
.. _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`.
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: c F
M-x notmuch-show-stash-filename
doc/emacs: add documentation for stashing 'c X' bindings This is the first of a series of changes requiring the extracted docstrings.
2018-06-14 02:32:41 +02:00
|docstring::notmuch-show-stash-filename|
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: c G
M-x notmuch-show-stash-git-send-email
doc/emacs: add documentation for stashing 'c X' bindings This is the first of a series of changes requiring the extracted docstrings.
2018-06-14 02:32:41 +02:00
|docstring::notmuch-show-stash-git-send-email|
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: c I
M-x notmuch-show-stash-message-id-stripped
doc/emacs: add documentation for stashing 'c X' bindings This is the first of a series of changes requiring the extracted docstrings.
2018-06-14 02:32:41 +02:00
|docstring::notmuch-show-stash-message-id-stripped|
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: c L
M-x notmuch-show-stash-mlarchive-link-and-go
doc/emacs: add documentation for stashing 'c X' bindings This is the first of a series of changes requiring the extracted docstrings.
2018-06-14 02:32:41 +02:00
|docstring::notmuch-show-stash-mlarchive-link-and-go|
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: c T
M-x notmuch-show-stash-tags
doc/emacs: add documentation for stashing 'c X' bindings This is the first of a series of changes requiring the extracted docstrings.
2018-06-14 02:32:41 +02:00
|docstring::notmuch-show-stash-tags|
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: c c
M-x notmuch-show-stash-cc
doc/emacs: add documentation for stashing 'c X' bindings This is the first of a series of changes requiring the extracted docstrings.
2018-06-14 02:32:41 +02:00
|docstring::notmuch-show-stash-cc|
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: c d
M-x notmuch-show-stash-date
doc/emacs: add documentation for stashing 'c X' bindings This is the first of a series of changes requiring the extracted docstrings.
2018-06-14 02:32:41 +02:00
|docstring::notmuch-show-stash-date|
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: c f
M-x notmuch-show-stash-from
doc/emacs: add documentation for stashing 'c X' bindings This is the first of a series of changes requiring the extracted docstrings.
2018-06-14 02:32:41 +02:00
|docstring::notmuch-show-stash-from|
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: c i
M-x notmuch-show-stash-message-id
doc/emacs: add documentation for stashing 'c X' bindings This is the first of a series of changes requiring the extracted docstrings.
2018-06-14 02:32:41 +02:00
|docstring::notmuch-show-stash-message-id|
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: c l
M-x notmuch-show-stash-mlarchive-link
doc/emacs: add documentation for stashing 'c X' bindings This is the first of a series of changes requiring the extracted docstrings.
2018-06-14 02:32:41 +02:00
|docstring::notmuch-show-stash-mlarchive-link|
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: c s
M-x notmuch-show-stash-subject
doc/emacs: add documentation for stashing 'c X' bindings This is the first of a series of changes requiring the extracted docstrings.
2018-06-14 02:32:41 +02:00
|docstring::notmuch-show-stash-subject|
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: c t
M-x notmuch-show-stash-to
doc/emacs: add documentation for stashing 'c X' bindings This is the first of a series of changes requiring the extracted docstrings.
2018-06-14 02:32:41 +02:00
|docstring::notmuch-show-stash-to|
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: c ?
M-x notmuch-subkeymap-help
Show all available copying commands
doc/emacs: add documentation for stashing 'c X' bindings This is the first of a series of changes requiring the extracted docstrings.
2018-06-14 02:32:41 +02:00
doc: add some documentation about duplicate files. This is mainly motivated by the new emacs-UI features to select duplicates, but hopefully it will help demystify things for users of the CLI as well.
2022-07-31 01:45:51 +02:00
.. _emacs-show-duplicates:
Dealing with duplicates
-----------------------
doc: fix typos
2023-04-13 15:52:11 +02:00
If there are multiple files with the same :mailheader:`Message-ID`
doc: add some documentation about duplicate files. This is mainly motivated by the new emacs-UI features to select duplicates, but hopefully it will help demystify things for users of the CLI as well.
2022-07-31 01:45:51 +02:00
(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
doc/emacs: replace emacscmd with el:define-key This allows us to eliminate the ad-hoc emacscmd directive / role, and improve indexing. doc/emacs: convert remaining uses of emacscmd to define-key This allows us to remove the no-longer used object type.
2022-07-31 13:33:21 +02:00
.. el:define-key:: %
M-x notmuch-show-choose-duplicate
doc: add some documentation about duplicate files. This is mainly motivated by the new emacs-UI features to select duplicates, but hopefully it will help demystify things for users of the CLI as well.
2022-07-31 01:45:51 +02:00
|docstring::notmuch-show-choose-duplicate|
doc: initial documentation for notmuch-tree mode
2018-05-21 22:08:55 +02:00
.. _notmuch-tree:
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
notmuch-tree
============
doc: initial documentation for notmuch-tree mode
2018-05-21 22:08:55 +02:00
``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.
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: c
doc/emacs: add documentation for stashing 'c X' bindings This is the first of a series of changes requiring the extracted docstrings.
2018-06-14 02:32:41 +02:00
:ref:`show-copy`
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: <return>
doc: initial documentation for notmuch-tree mode
2018-05-21 22:08:55 +02:00
Displays that message.
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: N
doc: initial documentation for notmuch-tree mode
2018-05-21 22:08:55 +02:00
Move to next message
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: P
doc: initial documentation for notmuch-tree mode
2018-05-21 22:08:55 +02:00
Move to previous message
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: n
doc: initial documentation for notmuch-tree mode
2018-05-21 22:08:55 +02:00
Move to next matching message
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: p
doc: initial documentation for notmuch-tree mode
2018-05-21 22:08:55 +02:00
Move to previous matching message
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: o
M-x notmuch-tree-toggle-order
doc: new notmuch show --sort and related emacs commands New --sort CLI option documented in notmuch-show's man page, and notmuch-search-toggle-order mentioned in doc/notmuch-emacs.rst and devel/emacs-keybindings.org (in the latter, there's also some whitespace changes in a table introduced by org-mode).
2021-07-02 22:44:24 +02:00
|docstring::notmuch-tree-toggle-order|
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: l
M-x notmuch-tree-filter
emacs: new command notmuch-tree-filter This command is analogous to notmuch-filter, but is defined on tree mode buffers.
2021-08-22 02:50:48 +02:00
Filter or LIMIT the current search results based on an additional query string
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: t
M-x notmuch-tree-filter-by-tag
emacs: new command notmuch-tree-filter-by-tag This new command for notmuch-tree-mode is analogous to notmuch-search-filter-by-tag, bound to "t" in notmuch-search-mode; it gets therefore the same "t" keybinding in notmuch-tree-mode (replacing the current assignment to notmuch-search-by-tag).
2021-08-22 02:50:49 +02:00
Filter the current search results based on an additional tag
emacs: Add new option notmuch-search-hide-excluded The new notmuch-search-hide-excluded option allows users to configure whether to show or hide excluded messages (as determined by search.exclude_tags in the local notmuch config file). It defaults to true for now to maintain backwards-compatibility with how notmuch-{search,tree} already worked. New commands notmuch-search-toggle-hide-excluded and notmuch-tree-toggle-exclude have also been added. They toggle the value of notmuch-search-hide-excluded for the search in the current search or tree buffer. It's bound to "i" in the respective keymaps for these modes. Lastly I've amended some calls to notmuch-tree and notmuch-unthreaded which didn't pass through the buffer local value of notmuch-search-oldest-first (and now notmuch-search-exclude). Examples of where I've done this include: + notmuch-jump-search + notmuch-tree-from-search-current-query + notmuch-unthreaded-from-search-current-query + notmuch-tree-from-search-thread A new test file for Emacs has been added which covers the usage of the new `notmuch-search-hide-excluded' option and interactively hiding or showing mail with excluded tags. These test cover the basic usage of the `notmuch-search-toggle-hide-excluded' command in notmuch-search, notmuch-tree and notmuch-unthreaded searches. These tests also cover the persistence of the current value of the hide-excluded mail option as a user switches from between these different search commands. [1]: id:87ilxlxsng.fsf@kisara.moe Amended-by: db, fix indentation in T461-emacs-search-exclude.sh
2024-03-10 19:57:41 +01:00
.. el:define-key:: i
Toggle whether to show messages with excluded tags in search results.
emacs: new command notmuch-tree-filter-by-tag This new command for notmuch-tree-mode is analogous to notmuch-search-filter-by-tag, bound to "t" in notmuch-search-mode; it gets therefore the same "t" keybinding in notmuch-tree-mode (replacing the current assignment to notmuch-search-by-tag).
2021-08-22 02:50:49 +02:00
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: g
=
Emacs: bind "g" to 'notuch-refresh-this-buffer Using "g" for refresh operations is a pretty common Emacs convention, codified by `special-mode' in simple.el.
2019-02-16 21:27:30 +01:00
Refresh the buffer
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: ?
doc: initial documentation for notmuch-tree mode
2018-05-21 22:08:55 +02:00
Display full set of key bindings
doc: new notmuch show --sort and related emacs commands New --sort CLI option documented in notmuch-show's man page, and notmuch-search-toggle-order mentioned in doc/notmuch-emacs.rst and devel/emacs-keybindings.org (in the latter, there's also some whitespace changes in a table introduced by org-mode).
2021-07-02 22:44:24 +02:00
As is the case with :ref:`notmuch-search`, the presentation of results
can be controlled by the variable ``notmuch-search-oldest-first``.
doc/emacs: replace use of emacsvar with el:defcustom Mainly this allows dropping the ad-hoc directive emacsvar
2022-07-31 13:33:22 +02:00
.. el:defcustom:: notmuch-tree-result-format
doc/emacs: add docstring and example for n-tree-result-format This example is based on one originally by Jon Hurst.
2022-07-16 23:22:26 +02:00
|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)")))
doc/emacs: replace use of emacsvar with el:defcustom Mainly this allows dropping the ad-hoc directive emacsvar
2022-07-31 13:33:22 +02:00
See also :el:defcustom:`notmuch-search-result-format` and
:el:defcustom:`notmuch-unthreaded-result-format`.
doc/emacs: add docstring for notmuch-unthreaded-result-format. The main change is actually updating cross references.
2022-07-16 23:22:28 +02:00
emacs: notmuch-tree-outline-mode With this mode, one can fold trees in the notmuch-tree buffer as if they were outlines, using all the commands provided by outline-minor-mode. We also define a couple of movement commands that, optional, will ensure that only the thread around point is unfolded. The implementation is based on registering a :level property in the messages p-list, that is then used by outline-minor-mode to to recognise headers. Amended by db: Copy docstring to manual and edit for presentation. Add two tests. Fix typo "wether".
2022-12-13 03:15:42 +01:00
.. _notmuch-tree-outline:
notmuch-tree-outline
--------------------
When this mode is set, each thread and subthread in the results
list is treated as a foldable section, with its first message as
its header.
The mode just makes available in the tree buffer all the
keybindings in info:emacs#Outline_Mode, and binds the following
additional keys:
.. el:define-key:: <tab>
Cycle visibility state of the current message's tree.
.. el:define-key:: <M-tab>
Cycle visibility state of all trees in the buffer.
The behaviour of this minor mode is affected by the following
customizable variables:
.. el:defcustom:: notmuch-tree-outline-enabled
|docstring::notmuch-tree-outline-enabled|
.. el:defcustom:: notmuch-tree-outline-visibility
|docstring::notmuch-tree-outline-visibility|
.. el:defcustom:: notmuch-tree-outline-auto-close
|docstring::notmuch-tree-outline-auto-close|
.. el:defcustom:: notmuch-tree-outline-open-on-next
|docstring::notmuch-tree-outline-open-on-next|
doc/emacs: add docstring and example for n-tree-result-format This example is based on one originally by Jon Hurst.
2022-07-16 23:22:26 +02:00
doc/emacs: add minimal documentation for notmuch-unthreaded mode. If nothing else it means the mode is discoverable by browsing the documentation, and also provides a target for links when enumerating modes.
2022-02-12 21:27:32 +01:00
.. _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`.
doc: new notmuch show --sort and related emacs commands New --sort CLI option documented in notmuch-show's man page, and notmuch-search-toggle-order mentioned in doc/notmuch-emacs.rst and devel/emacs-keybindings.org (in the latter, there's also some whitespace changes in a table introduced by org-mode).
2021-07-02 22:44:24 +02:00
doc/emacs: replace use of emacsvar with el:defcustom Mainly this allows dropping the ad-hoc directive emacsvar
2022-07-31 13:33:22 +02:00
.. el:defcustom:: notmuch-unthreaded-result-format
doc/emacs: add docstring for notmuch-unthreaded-result-format. The main change is actually updating cross references.
2022-07-16 23:22:28 +02:00
|docstring::notmuch-unthreaded-result-format|
doc/emacs: replace use of emacsvar with el:defcustom Mainly this allows dropping the ad-hoc directive emacsvar
2022-07-31 13:33:22 +02:00
See also :el:defcustom:`notmuch-search-result-format` and
:el:defcustom:`notmuch-tree-result-format`.
doc/emacs: add docstring for notmuch-unthreaded-result-format. The main change is actually updating cross references.
2022-07-16 23:22:28 +02:00
doc: Emacs manual improvements and expansions Fix several typos, improve general wording and flow, and add some information on notmuch-jump.
2014-10-03 16:27:26 +02:00
Global key bindings
===================
doc/emacs: add minimal documentation for notmuch-unthreaded mode. If nothing else it means the mode is discoverable by browsing the documentation, and also provides a target for links when enumerating modes.
2022-02-12 21:27:32 +01:00
Several features are accessible from most places in notmuch through the
doc: Emacs manual improvements and expansions Fix several typos, improve general wording and flow, and add some information on notmuch-jump.
2014-10-03 16:27:26 +02:00
following key bindings:
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: j
doc: Emacs manual improvements and expansions Fix several typos, improve general wording and flow, and add some information on notmuch-jump.
2014-10-03 16:27:26 +02:00
Jump to saved searches using :ref:`notmuch-jump`.
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: k
docs: add initial documentation for notmuch-tag-jump This is mainly to improve discoverability. It seems that doing variable cross-references is not easy without using some sphinx extension/customization.
2018-05-21 22:08:56 +02:00
Tagging operations using :ref:`notmuch-tag-jump`
doc/emacs: use define-key instead of hard-coding markup Add keys to index. Allow indexing of both keys and commands. Use standard typesetting for multiple keybindings.
2022-07-31 13:33:23 +02:00
.. el:define-key:: C-_
C-/
C-x u
Undo previous tagging operation using :any:`notmuch-tag-undo`
emacs: Document undo binding. This messes up whitespace, which will require a global change to fix.
2022-02-12 21:27:41 +01:00
doc: fix references in notmuch-emacs.rst Fix make sphinx-texinfo warnings: WARNING: undefined label: notmuch-jump (if the link has no caption the label must precede a section header) WARNING: undefined label: notmuch-saved-searches (if the link has no caption the label must precede a section header)
2016-11-05 21:18:15 +01:00
.. _notmuch-jump:
doc: Emacs manual improvements and expansions Fix several typos, improve general wording and flow, and add some information on notmuch-jump.
2014-10-03 16:27:26 +02:00
notmuch-jump
------------
doc: fix references in notmuch-emacs.rst Fix make sphinx-texinfo warnings: WARNING: undefined label: notmuch-jump (if the link has no caption the label must precede a section header) WARNING: undefined label: notmuch-saved-searches (if the link has no caption the label must precede a section header)
2016-11-05 21:18:15 +01:00
Saved searches configured through :ref:`saved-searches` can
doc: Emacs manual improvements and expansions Fix several typos, improve general wording and flow, and add some information on notmuch-jump.
2014-10-03 16:27:26 +02:00
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
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.
docs: add initial documentation for notmuch-tag-jump This is mainly to improve discoverability. It seems that doing variable cross-references is not easy without using some sphinx extension/customization.
2018-05-21 22:08:56 +02:00
.. _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.
doc/emacs: replace use of emacsvar with el:defcustom Mainly this allows dropping the ad-hoc directive emacsvar
2022-07-31 13:33:22 +02:00
.. el:defcustom:: notmuch-tagging-keys
docs: add initial documentation for notmuch-tag-jump This is mainly to improve discoverability. It seems that doing variable cross-references is not easy without using some sphinx extension/customization.
2018-05-21 22:08:56 +02:00
doc/emacs: document notmuch-tagging-keys Calling these "Global keys" is arguably a bit of a stretch, but they do work in all notmuch modes except notmuch-hello.
2018-06-14 02:32:43 +02:00
|docstring::notmuch-tagging-keys|
docs: add initial documentation for notmuch-tag-jump This is mainly to improve discoverability. It seems that doing variable cross-references is not easy without using some sphinx extension/customization.
2018-05-21 22:08:56 +02:00
emacs: add notmuch-tag-undo Keybindings are deferred to a future commit.
2022-02-12 21:27:39 +01:00
notmuch-tag-undo
----------------
doc: fix typos
2023-04-13 15:52:11 +02:00
Each notmuch buffer supporting tagging operations (i.e. buffers in
emacs: add notmuch-tag-undo Keybindings are deferred to a future commit.
2022-02-12 21:27:39 +01:00
:any:`notmuch-show`, :any:`notmuch-search`, :any:`notmuch-tree`, and
:any:`notmuch-unthreaded` mode) keeps a local stack of tagging
doc/emacs: replace emacscmd with el:define-key This allows us to eliminate the ad-hoc emacscmd directive / role, and improve indexing. doc/emacs: convert remaining uses of emacscmd to define-key This allows us to remove the no-longer used object type.
2022-07-31 13:33:21 +02:00
operations. These can be undone via :any:`notmuch-tag-undo`. By default
emacs: add notmuch-tag-undo Keybindings are deferred to a future commit.
2022-02-12 21:27:39 +01:00
this is bound to the usual Emacs keys for undo.
doc/emacs: replace emacscmd with el:define-key This allows us to eliminate the ad-hoc emacscmd directive / role, and improve indexing. doc/emacs: convert remaining uses of emacscmd to define-key This allows us to remove the no-longer used object type.
2022-07-31 13:33:21 +02:00
.. el:define-key:: C-_
C-/
C-x u
M-x notmuch-tag-undo
emacs: add notmuch-tag-undo Keybindings are deferred to a future commit.
2022-02-12 21:27:39 +01:00
|docstring::notmuch-tag-undo|
doc/emacs: document notmuch-cycle-notmuch-buffers For some reason I couldn't find this when I searched, so add it to the manual.
2018-06-14 02:32:45 +02:00
Buffer navigation
=================
doc/emacs: replace emacscmd with el:define-key This allows us to eliminate the ad-hoc emacscmd directive / role, and improve indexing. doc/emacs: convert remaining uses of emacscmd to define-key This allows us to remove the no-longer used object type.
2022-07-31 13:33:21 +02:00
.. el:define-key:: M-x notmuch-cycle-notmuch-buffers
doc/emacs: define and use emacsvar and emacscmd markup This makes it easier to navigate the merged index of all of the notmuch documentation.
2022-07-01 12:40:39 +02:00
doc/emacs: document notmuch-cycle-notmuch-buffers For some reason I couldn't find this when I searched, so add it to the manual.
2018-06-14 02:32:45 +02:00
|docstring::notmuch-cycle-notmuch-buffers|
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
Configuration
=============
.. _importing:
Importing Mail
--------------
doc/emacs: replace emacscmd with el:define-key This allows us to eliminate the ad-hoc emacscmd directive / role, and improve indexing. doc/emacs: convert remaining uses of emacscmd to define-key This allows us to remove the no-longer used object type.
2022-07-31 13:33:21 +02:00
.. el:define-key:: M-x notmuch-poll
doc/emacs: define and use emacsvar and emacscmd markup This makes it easier to navigate the merged index of all of the notmuch documentation.
2022-07-01 12:40:39 +02:00
doc/emacs: document notmuch-poll* The current "documentation" for these variables consists of only the variable names.
2018-06-14 02:32:44 +02:00
|docstring::notmuch-poll|
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
doc/emacs: replace use of emacsvar with el:defcustom Mainly this allows dropping the ad-hoc directive emacsvar
2022-07-31 13:33:22 +02:00
.. el:defcustom:: notmuch-poll-script
doc/emacs: define and use emacsvar and emacscmd markup This makes it easier to navigate the merged index of all of the notmuch documentation.
2022-07-01 12:40:39 +02:00
doc/emacs: document notmuch-poll* The current "documentation" for these variables consists of only the variable names.
2018-06-14 02:32:44 +02:00
|docstring::notmuch-poll-script|
doc: added 'Init File' section to notmuch-emacs info source While adding that fixed (also other) typos noticed by aspell(1) run, and capitalized Emacs and (most) Notmuch terms to match how emacs Info documentation seems to look in general.
2014-04-03 22:53:03 +02:00
emacs: drop setting mail-user-agent, and document how to set it After some discussion [1], I decided it is better to make notmuch users who rely on this behaviour customize mail-user-agent. This is consistent with the behaviour of other emacs mail packages. [1]: id:87k0nuhfrk.fsf@toryanderson.com
2021-06-05 01:05:31 +02:00
Sending Mail
------------
doc/emacs: replace use of emacsvar with el:defcustom Mainly this allows dropping the ad-hoc directive emacsvar
2022-07-31 13:33:22 +02:00
.. el:defcustom:: mail-user-agent
emacs: drop setting mail-user-agent, and document how to set it After some discussion [1], I decided it is better to make notmuch users who rely on this behaviour customize mail-user-agent. This is consistent with the behaviour of other emacs mail packages. [1]: id:87k0nuhfrk.fsf@toryanderson.com
2021-06-05 01:05:31 +02:00
doc/emacs: use :code: for some missing references It's not obvious how to reference (non-notmuch) emacs variables and functions in a sphinx document.
2021-08-22 05:51:09 +02:00
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`.
emacs: drop setting mail-user-agent, and document how to set it After some discussion [1], I decided it is better to make notmuch users who rely on this behaviour customize mail-user-agent. This is consistent with the behaviour of other emacs mail packages. [1]: id:87k0nuhfrk.fsf@toryanderson.com
2021-06-05 01:05:31 +02:00
doc/emacs: replace use of emacsvar with el:defcustom Mainly this allows dropping the ad-hoc directive emacsvar
2022-07-31 13:33:22 +02:00
.. el:defcustom:: message-dont-reply-to-names
emacs: use message-dont-reply-to-names when composing replies notmuch-mua functions for replies now use the built-in customizable variable message-dont-reply-to-names with the same semantics as message-mode.
2022-06-09 04:11:45 +02:00
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.
doc: added 'Init File' section to notmuch-emacs info source While adding that fixed (also other) typos noticed by aspell(1) run, and capitalized Emacs and (most) Notmuch terms to match how emacs Info documentation seems to look in general.
2014-04-03 22:53:03 +02:00
Init File
---------
When Notmuch is loaded, it will read the ``notmuch-init-file``
(``~/.emacs.d/notmuch-config`` by default) file. This is normal Emacs Lisp
file and can be used to avoid cluttering your ``~/.emacs`` with Notmuch
stuff. If the file with ``.elc``, ``.elc.gz``, ``.el`` or ``.el.gz``
suffix exist it will be read instead (just one of these, chosen in this
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.
Reference in a new issue Copy permalink