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.
The first sentence should fit on the first line. It is okay if
the first sentence/line does not contain all the information that
the rest of the doc-string covers.
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.
Previously in message-show mode message's first header line (From
header) was always indented, even if user had turned thread
indentation off with "<" (notmuch-show-toggle-thread-indentation)
command.
This change modifies notmuch-show-insert-headerline function so that
it doesn't indent the first header line if notmuch-show-indent-content
variable is nil.
This change also modifies tests so that they expect this new output
format:
test/emacs-show.expected-output/notmuch-show-indent-thread-content-off
- 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.
It's a bit weird to avoid having to write the "(setq ... )" more than
once, just because we can. In a language that uses '=' for the same
purpose we also happily use that once per assignment.
While there are no benefit to using just one 'setq' there are some
drawbacks. It is not always clear on first what is a key and what a
value and as a result it is easy to make a mistake. Also it becomes
harder to comment out just one assignment.
Most people who write lots of lisp tend to only sparsely use empty
"separator" lines within forms. In lisp they feel unnecessary and
since most files stick to this convention we get a bit confused
when there are extra empty lines. It feels like the s-expressions
are falling into pieces.
All of this is especially true between a function's doc-string and
body because the doc-string is colored differently, which visually
already separates it quite sufficiently from the code that follows.
In notmuch-show buffer insert invisible U+200E LEFT-TO-RIGHT MARK
character at the beginning of message header paragraph if the From
header contains a right-to-left character. This ensures that the
header paragraph is always rendered in left-to-right mode.
See Emacs Lisp reference manual section "(elisp) Bidirectional
Display" for more info.
Fixed emacs docstrings to be consistent. No functional change.
- removed some (accidental) indentation
- removed some trailing newlines
- added trailing periods where missing (some exclusions)
Starting with Emacs 27 the old `cl' implementation is finally
considered obsolete. Previously its use was strongly discouraged
at run-time but one was still allowed to use it at compile-time.
For the most part the transition is very simple and boils down to
adding the "cl-" prefix to some symbols. A few replacements do not
follow that simple pattern; e.g. `first' is replaced with `car',
even though the alias `cl-first' exists, because the latter is not
idiomatic emacs-lisp.
In a few cases we start using `pcase-let' or `pcase-lambda' instead
of renaming e.g. `first' to `car'. That way we can remind the reader
of the meaning of the various parts of the data that is being
deconstructed.
An obsolete `lexical-let' and a `lexical-let*' are replaced with their
regular variants `let' and `let*' even though we do not at the same
time enable `lexical-binding' for that file. That is the right thing
to do because it does not actually make a difference in those cases
whether lexical bindings are used or not, and because this should be
enabled in a separate commit.
We need to explicitly depend on the `cl-lib' package because Emacs
24.1 and 24.2 lack that library. When using these releases we end
up using the backport from GNU Elpa.
We need to explicitly require the `pcase' library because
`pcase-dolist' was not autoloaded until Emacs 25.1.
This is the non-deprecated way to use completing-read. Additionally
the old use was broken when using ivy for completing-read. For user's
using completing-read-default they won't see the default URL now, but
if they hit enter it will be visited. Alternatively they can select
it with M-n.
From the completing-read documentation for initial-input:
This feature is deprecated--it is best to pass nil for INITIAL-INPUT
and supply the default value DEF instead. The user can yank the
default value into the minibuffer easily using M-n.
Additionally collection is now all urls, rather than all but the
first. I'm not sure why "(cdr urls)" was previously done.
We have shortcuts S and Z to let the user switch to Search view and
Tree view with the current search. Add U to let the user switch to
unthreaded view from the current search, and ensure that S and Z
switch from unthreaded to search and tree veiew respectively.
This commit introduces a new 'unthreaded' search mode where each
matching message is shown on a separate line. It shares almost all of
its code with tree view. Subsequent commits will allow it to diverge
slightly in appearance.
Since only the first line of the documentation is shown by the
help command, it is confusing when "x" and "a" seem to have the same
binding in show-mode. This commit makes the two function documentations
first lines different and (hopefully) clearer.
Add a new binding when looking at messages, B, that prompts with a
list of URLs found in the current message, if any. Open the one that
is selected in a browser.
amended by db: s/--browse-urls/-browse-urls/
`mm-inline-text-html-with-images' was removed from mm-decode.el in
2016 and replaced with `mm-html-inhibit-images'.
`gnus-select-frame-set-input-focus' was removed from gnus-util.el in
2016 and existed only for XEmacs compatibility.
Correct URLs that have crept into the notmuch codebase with http://
when https:// is possible.
As part of this conversion, this changeset also indicates the current
preferred upstream URLs for both gmime and sup. the new URLs are
https-enabled, the old ones are not.
This also fixes T310-emacs.sh, thanks to Bremner for catching it.
Dynamically bind enriched-decode-display-prop when inserting
text/enriched part. This complements commit 9b05823838 for
emacs versions before 24.4 which do not have advice-add
functionality.
Since emacs 25.3 this particular bug is fixed.
Switch to a local version of enriched-decode-display-prop if we
encounter a text/enriched part. This is to mitigate
https://bugs.gnu.org/28350. Normally it would be prudent to remove the
override afterwards, but in this case just leave it in.
Notes from db:
This doesn't disable text/enriched, just one feature of it.
The queries "" and "*" are special cased in the notmuch library to
match all messages, but only if they're the entire query. They can't
be combined with other queries, such as "* AND foo", in which case
they "leak" down to the Xapian query parser.
Notmuch show and tree buffers inadvertently combine the thread query
with said special queries, causing incorrect collapsing of
messages. Handle the special queries specially. We already do a
similar thing in notmuch-search-filter.
Emacs' major modes can facilitate navigation in their buffers by
supporting Imenu. In such major modes, launching Imenu (M-x imenu)
makes Emacs display a list of items (e.g., function definitions in a
code buffer). Selecting an item from this list moves point to this
item.
This patch adds Imenu support to both notmuch-show and notmuch-search
buffers:
* in notmuch-show, Imenu will present a list of all messages in the
currently visible thread;
* in notmuch-search, Imenu will present a list of all messages in the
search buffer.
Gnus seems to display application/zip and application/tar by
default. This doesn't seem desirable so we override it.
We only override if the user has not customized
mm-inline-override-types themselves.
Provide functionality to resume editing a message previously saved with
notmuch-draft-save, including decoding the X-Notmuch-Emacs-Secure
header.
Resume gets the raw file from notmuch and using the emacs function
mime-to-mml reconstructs the message (including attachments).
'e' is bound to resume a draft from show or tree mode.
notmuch-show--build-buffer now queries a list of queries built by the
former. This simplifies the logic. It also provides an easy place to
experiment with alternate sets of queries for given notmuch-show-*
variables (e.g. users can use advice-add to do so in a surgical way).
