Some people (e.g: me) prefer to read their email with threaded
representation by default.
Without this commit, I have to run "notmuch-search" (autoloaded)
first to get "notmuch-tree" loaded.
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".
...and bind these to "E" in their respective keymaps.
Expected to be called interactively, then using read-from-minibuffer
with current search string as initial contents for editing.
(Noninteractive use makes little sense, but is supported.)
With this one can expand (as an opposite to limit) their
query and have e.g. (some of their) saved searches as search
"templates".
While at it, removed `(defvar notmuch-search-query-string)` from
notmuch-tree.el; it is unused (`notmuch-tree-basic-query` is used
instead).
Thanks to Jose Antonio Ortega Ruiz for his example for notmuch-tree
code, and better interactive use.
Hook run when the tree insertion process finishes its job.
--
This patch supersedes <id:20220816214023.1523322-1-jao@gnu.org>, but
changing the new variable name.
Right now, it can be used for silly things like removing or changing
the the "End of search." hardcoded message in the tree buffer. But
also for more sophisticated things like folding all threads in add-ons
like my outline mode for tree buffers (to be submitted).
Signed-off-by: jao <jao@gnu.org>
It seems redundant to have the previous example, since the default
value is always show by describe variable.
Enforce more restrictions on the keys in the alist, since arbitrary
strings don't work as field names.
Document that functions can be used in lieu of field names.
The only functionality actually used by notmuch is the base function
notmuch-query-get-threads; the other functions in this file have
nothing to do with that (single) use. Move that function into
notmuch-lib.el and rename to reflect use. Deprecate the other
functions in notmuch-query.el.
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.
The docstrings for notmuch-tree-match-author-face and
notmuch-tree-no-match-author-face incorrectly match the docstring of
notmuch-tree-match-date-face.
The missing docstring causes a blank in the notmuch-help display
[1]. Since the function is a simple wrapper for notmuch-tree, it seems
fair to forward the reader there for more detailed information.
[1]: id:878sape5a9.fsf@disroot.org
New customizable variable, notmuch-tree-thread-symbols, that allows
tweaking of how trees in a forest are represented. For instance, one
can now choose to use an hyphen rather than a white space as a prefix,
or replace the character(s) used to draw arrows.
Amended-By: db; delete errant '3'
Initially just set the working directory, to avoid (the implicit)
call-process crashing when the default-directory points to a
non-existent location.
Use of a macro here is over-engineering for this change, but the same
change needs to be applied to several other process creation
primitives.
If the car of an element in notmuch-tree-result-format or
notmuch-unthreaded-result-format is a function, insert the result of
calling the function into the buffer.
This is a bit of a cheat, since the format does not actually
change. On the other hand it is fairly common to do something like
this to shared libary SONAMEs when the ABI changes in some subtle way.
It does rely on the format-version argument being early enough on the
command line to generate a sensible error message.
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).
When moving between message in a tree or show buffer, the message at
point is marked as read. Likewise when creating such a buffer, then
the message that is initially at point is supposed to be marked as
read as well.
The latter worked for `notmuch-show' but not for `notmuch-tree'.
Press "RET" or "M-RET" in a search buffer to observe these behaviors.
In both cases the marking is supposed to be done by the function
`notmuch-show-command-hook'. In the case of `notmuch-show' that
function is added directly to `post-command-hook'.
`notmuch-tree' instead adds the function `notmuch-tree-command-hook'
to `post-command-hook' and that calls `notmuch-show-command-hook',
in the respective show buffer, but of course only if that exists.
Because the tree buffer is created asynchronously, the show buffer
doesn't exist yet by the time the `post-command-hook' is run, so
we have to explicitly run `notmuch-tree-command-hook' once the
show buffer exists.
The show buffer is created when `notmuch-tree-goto-and-insert-msg'
calls `notmuch-tree-show-message-in'. `notmuch-tree-process-filter'
is what finally brings us here.
This is more efficient than notmuch-show-only-matching-messages, since
we do not parse the potentially large thread structure to find a
single message.
This is only a partial fix for notmuch-tree view, because displaying
the thread structure in the tree-mode window still crashes on long
threads. It is however enough to make unthreaded view handle long
threads.
- declare-function notmuch-unthreaded lacked file name
- declare-function notmuch-search had differently named last arg
- note: check-declare-directory did not complain about that
- declare-function notmuch-search-show-thread without nil
- some functions declared to be in different file than those
existed ("notmuch" -> "notmuch-lib")
- some related function/declare lines were (/are now) wider than
80-columns; added line breaks (and proper indentation) there
When called from code, then this function returns non-nil when the
message at point is a matched message. However it does nothing at all
to present that information to the user when it called interactively.
It is therefore safe to conclude that nobody is using this as a
command.
We need to load `cl-lib' at run-time because we use more from it than
just macros. Never-the-less many, but not all libraries required it
only at compile-time, which we got away with because at least some
libraries already required it at run-time as well.
We use `cl-lib' and (currently to a lesser extend) `pcase' throughout
the code-base, which means that we should require these features in
most libraries.
In the past we tried to only require these features in just the
libraries that actually need them, without fully succeeding. We did
not succeed in doing so because that means we would have to check
every time that we use a function from these features whether they
are already being required in the current library.
An alternative would be to add the `require' forms at the top of every
library but that is a bit annoying too.
In order to make sure that these features are loaded when needed but
also to keep the noise down we only require them in "notmuch-lib.el",
which most other libraries require, and in most of the few libraries
that do not do so, namely "notmuch-draft.el", "notmuch-message.el" and
"notmuch-parser.el". ("coolj.el", "make-deps.el", various generated
libraries, and "notmuch-compat.el" are left touched.)
To some extend this is a personal preference, but the preference is
strongly dependent on whether one is used to a language that makes it
necessary to use variables like this.
This makes it perfectly clear that we are first getting and then using
a "foo":
(use-foo (get-foo))
Sure this has to be read "inside out", but that's something one better
gets used to quickly when dealing with lisp. I don't understand why
one would want to write this instead:
(let ((the-foo (get-foo)))
(use-foo the-foo))
Both `get-foo' and `use-foo' are named in a way that make it very
clear that we are dealing with a "foo". Storing the value in an
additional variable `the-foo' does not make this any more clear.
On the contrary I makes the reader wonder why the author choose to
use a variable. Is the value used more than once? Is the value
being retrieved in one context and then used in another (e.g. when
the current buffer changes)?
The previous commit switched to lexical-binding but without dealing
with the new warnings about unused lexical arguments and variables.
This commit deals with most of them, in most cases by either removing
leftover bindings that are actually unnecessary, or by marking certain
arguments as "known to be unused" by prefixing their names with "_".
In the case of the functions named `notmuch-show-insert-...' the
amount of silencing that is required is a bit extreme and we might
want to investigate if there is a better way.
In the case of `notmuch-mua-mail', ignoring CONTINUE means that we do
not fully follow the intended behavior described in `compose-mail's
doc-string.
Doing so causes many new compile warnings. Some of these warnings
concern genuine changes in behavior that have to be addressed right
away.
Many other warnings are due to unused variables. Nothing has changed
here, except that the byte-compiler can now detect these pre-existing
and harmless issues. We delay addressing these issues so that we can
focus on the important ones here.
A third group of warnings concern arguments that are not actually used
inside the function but which cannot be removed because the functions
signature is dictated by some outside convention. Silencing these
warning is also delayed until subsequent commits.
`outline-minor-mode' treats comments that begin with three or more
semicolons as headings. That makes it very convenient to navigate
code and to show/hide parts of a file.
Elips libraries typically have four top-level sections, e.g.:
;;; notmuch.el --- run notmuch within emacs...
;;; Commentary:...
;;; Code:...
;;; notmuch.el ends here
In this package many libraries lack a "Commentary:" section, which is
not optimal but okay for most libraries, except major entry points.
Depending on how one chooses to look at it, the "... ends here" line
is not really a heading that begins a section, because it should never
have a "section" body (after all it marks eof).
If the file is rather short, then I left "Code:" as the only section
that contains code. Otherwise I split the file into multiple sibling
sections. The "Code:" section continues to contain `require' and
`declare-function' forms and other such "front matter".
If and only if I have split the code into multiple sections anyway,
then I also added an additional section named just "_" before the
`provide' form and shortly before the "...end here" line. This
section could also be called "Back matter", but I feel it would be
distracting to be that explicit about it. (The IMO unnecessary but
unfortunately still obligatory "... ends here" line is already
distracting enough as far as I am concerned.)
Before this commit some libraries already uses section headings, some
of them consistently. When a library already had some headings, then
this commit often sticks to that style, even at the cost inconsistent
styling across all libraries.
A very limited number of variable and function definitions have to be
moved around because they would otherwise end up in sections they do
not belong into.
Sections, including but not limited to their heading, can and should
be further improved in the future.
One should never bind unnamed commands in keymaps because doing that
makes it needlessly hard for users to change these bindings.
Replace such anonymous bindings with named commands that are generated
using macros and some boilerplate. Using macros is better than using a
simple loop because that makes it possible for `find-function' to find
the definitions. Eat your boilerplate--it forms character.
Admittedly this approach is quite ugly and it might be better to teach
the original commands to support different buffers directly instead of
requiring wrapper commands to do just that.
Never-the-less as a short-term solution this is better than what we
had before.
Since [1: f8bdba37] no key is bound to this command and it is
redundant because the behavior of `push-command' is identical
when called as a command.
1: f8bdba37d3
emacs: tree: remove binding for pressing button in message pane
Notmuch requires at least version 25 of Emacs now.
Adjust comments that previously referenced version 24 specifically,
even though they also apply to later releases. Remove documentation
and code that no longer applies.
- `mm-shr' no longer references `gnus-inhibit-images'.
This means that notmuch commands obey display-buffer-alist so the user
can customize how buffers show up.
It also permits the use of C-x 4 4, C-x 5 5 and C-x t t, available in
Emacs 28. For example, one can use C-x 4 4 M-x notmuch-jump-search RET
to open a saved search in another window rather than the current window.
Or in notmuch-search mode, C-x 5 5 RET to view the message at point in
a new frame.
notmuch-tree has custom buffer display logic, so bind
display-buffer-overriding-action to make pop-to-buffer-same-window
behave exactly as switch-to-buffer while that function is running.
Now that notmuch-tree-next-thread acts more like its notmuch-show
counterpart, let's update the binding to move to the next thread after
archiving.
Signed-off-by: William Casarin <jb55@jb55.com>
This introduces a new function called
notmuch-tree-next-thread-from-search which is analogous to
notmuch-show-next-thread. It will switch to the next or previous
thread from the parent search results.
We rename notmuch-tree-{prev,next}-thread to a more descriptive
notmuch-tree-{prev,next}-thread-in-tree to reflect the fact that it
only moves to the next thread in the current tree.
notmuch-tree-next-thread now switches to the next thread in the
current tree first, but if there are none, it looks for the next tree
in the search results.
This makes notmuch-tree feel more like notmuch-show when using the
M-Enter, M-n and M-p bindings.
Signed-off-by: William Casarin <jb55@jb55.com>
This variable will be used in a similar fashion to
notmuch-show-parent-buffer. It will be used to navigate between
threads from the parent search buffer.
Signed-off-by: William Casarin <jb55@jb55.com>
This function is being autoloaded using an autoload cookie, so it
shouldn't additionally be autoloaded using an `autoload' form.
When building libraries we don't actually load the autoloads file and
dropping the `autoload' form results in an error, which reveals a so
far unspecified dependency: `notmuch-tree' needs `notmuch-jump'.
Before this commit compiling (or even just loading) `notmuch-tree'
resulted in `notmuch-jump' being loaded because the former requires
`notmuch-lib', which autoloaded `notmuch-jump-search'.
The bug was that this dependency was not explicitly specified, which
we fix by adding the respective `require' form.
- The first sentence should fit on the first line in full. This is
even the case when that causes the line to get a bit long. If it
gets very long, then it should be made shorter.
- Even even the second sentence would fit on the first line, if it
just provides some details, then it shouldn't be done.
- Symbols are quoted like `so'.
- There is no clear rule on how to (not) quote non-atomic
s-expressions, but quoting like '(this) is definitely weird.
- It is a good idea to remember that \" becomes " and to take
that in mind when adjusting the automatic filling by hand.
- Use the imperative form.
- Arguments are written in all uppercase.
