test: add (back) upgrade tests

In ee897cab8b721 the upgrade tests from pre v3 databases were
removed. The reasons for that are still valid, but we should still
test the code paths that do the upgrade, and it is relatively
straightforward to do that for v3 to v3 upgrades.

test/T391-python-cffi

Make bindings test verbose. This helps in debugging.

test/T750-gzip: don't compress the xapian database

This causes mysterious failures in trying to detect if a database
exists.

emacs: avoid type errors due to nil as content-type

The output of "notmuch show --format=sexp --format-version=4"
may contain `:content-type' entries with `nil' as the value,
when it fails to detect the correct value.  Account for that
in a few places where we would otherwise risk a type error.

Note that `string=' does not choke on `nil' because it uses
the `symbol-name' when encountering a symbol.

emacs: notmuch-show--get-cid-content: cosmetics

emacs: notmuch-show--register-cids: fix names of bindings

emacs: notmuch-mua-add-more-hidden-headers: use local binding

emacs: notmuch-address-expand-name: use the actual initial-input

Users may type some text into the buffer on an address line, before
actually invoking address completion.  We now use that text as the
initial input when we begin address completion.

Previously we did knowingly replace the actual initial input with some
completion candidate that happens to match. Which candidate is used is
essentially random, at least when the actual initial input is short.
As a result users very often had to begin completion by deleting the
less than helpful "initial input".

emacs: allow opting out of notmuch's address completion

IMO Notmuch should not override the default completion mechanism by
default, at least not globally. But since users are already used to
this behavior it is probably too late to change it. Do the next best
thing and at least allow users to opt out.

emacs: notmuch-tree-get-match: No longer define as command

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.

emacs: use string-empty-p

emacs: make subr-x available in all libraries

Like `cl-lib' and `pcase', which are already available in all
libraries, `subr-x' also provided many useful functions that
we would like to use.

Making `subr-x' available in every library from the get-go means
that we can use the functions it defines without having to double
check every single time, whether the feature is already available
in the current library.

emacs: improve how cl-lib and pcase are required

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.)

emacs: avoid unnecessary let-bindings

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)?

emacs: reorder notmuch.el a bit

emacs: notmuch-search-stash-thread-id: use notmuch-search-query-string

No longer use the function `notmuch-search-get-query', which does
nothing but return the value of that variable.  That function was
added in [1: f47eeac0] for use in `notmuch-read-query' along-side
related `notmuch-show-get-query' and `notmuch-tree-get-query' but
using it here makes little sense.

1: f47eeac0b0186c3559eb559c4f0bee0e1fac1961
   emacs: set default in notmuch-read-query

emacs: define a few variables as automatically buffer-local

Define these variables as automatically buffer-local, meaning that
they always become buffer-local when set unless explicitly told
otherwise using `setq-default' or when using the Custom interface.

Previously they were declared, which keeps the byte-compiler quiet but
is not actually the same as being defined.  `notmuch-search-mode' then
made them buffer-local in the current buffer and then set the local
values.  This works but is not kosher.

The definitions of the three non-option variables have to be moved up
a bit to enable the change in the next commit, which see.

emacs: remove variable notmuch-search-disjunctive-regexp

The value is the only possible value, it is only used in one
place, and using a global variable serves no purpose but to
make things more complicated.

emacs: various doc-string improvements

emacs: various comment improvements

emacs: various cosmetic improvements

emacs: notmuch-crypto-status-button-type: fix potential bug

The "help-echo" can potentially contain an unintended %-spec
so we have to make sure it would not be treated as such.

emacs: notmuch-mua.el: move all options into "Options" section

This is how we do it in other libraries.

emacs: notmuch-mua-prompt-for-sender: don't force Ido on users

We shouldn't force `ido-completion-read' on users who do not otherwise
use Ido.  Unfortunately simply turning on `ido-mode' does not change
every `completing-read' into a `ido-completing-read', instead it only
changes file and buffer completion.

I do realize that existing Ido users will initially dislike this
change, but I would like to encourage them to see this as an
opportunity to learn about Fido.

Unlike `ido-mode', build-in `fido-mode' confirms to the standard
completion API, so turning it on causes every `completing-read' to
use the Fido completion mechanism and which is similar to the Ido
mechanism:

> An enhanced `icomplete-mode' that emulates `ido-mode'.  This global
> minor mode makes minibuffer completion behave more like `ido-mode'
> than regular `icomplete-mode'."

emacs: notmuch-wash.el: require diff-mode at beginning of code

That's what we usually do.  Also do not declare variable
`diff-file-header-re' because it is defined in `diff-mode.el',
which we always require.

emacs: notmuch-message-apply-queued-tag-changes: cosmetics

emacs: define notmuch-message-queued-tag-changes as buffer-local

Also improve the doc-string.

emacs: silence compiler wrt notmuch-show-insert-part-text/plain

`notmuch-show-insert-part-text/plain' calls
`notmuch-show-insert-text/plain-hook' with two arguments
MSG and DEPTH. Currently all hook functions ignore MSG but
third-party functions may not.  One hook function uses DEPTH.

emacs: notmuch-wash-region-to-button: remove unused MSG argument

emacs: inline notmuch-sexp-eof into only caller

This function had a few issues.
- Neither its name nor the old comment before it is called made it
  clear what it does.
- It took one argument but didn't do anything with it.
- It's doc-string made a few claims, which are untrue and generally
  focused on details instead of that its purpose is.

emacs: notmuch-tag--get-formats: silence byte-compiler

`format-alist' is a global variable and the byte-compiler is unhappy
when a lexical function argument shadows a global (dynamic) binding.

emacs: deal with unused lexical arguments and variables

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.

emacs: use lexical-bindings in all libraries

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.

emacs: make headings outline-minor-mode compatible

`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.

emacs: avoid killing process buffer when process is still alive

In practice this probably does not make a difference or we would
have heard about it many times, but better be safe than sorry.

Process sentinels are called not only when the process has finished
but also on other state changes.

emacs: avoid passing around some redundant information

When running "notmuch" we use its full path but when displaying the
command to the user we show just its name for readability reasons.
Avoid passing around both representations because it is very easy
to get the name from the path.

Notmuch itself uses the involved functions just for "notmuch" but
there might be extensions that use them for other executable so we
forgo other potential simplifications.

emacs: notmuch-start-notmuch: avoid storing process buffer twice

The buffer of the error process is accessible using `process-buffer'.
We still have to store the error-buffer in the non-error process
because for that process `process-buffer' obviously returns its own
buffer.

emacs: notmuch-start-notmuch-sentinel: assert buffer is alive

emacs: notmuch-start-notmuch-error-sentinel: assert buffer is alive

emacs: notmuch-start-notmuch: remove backward compatibility code

We no longer support Emacs releases before version 25.1.

Also adjust the sentinels which only had to deal with
an error file when using an older Emacs release was used.

emacs: define new notmuch-search-item widget type

This is complex enough to warrant a dedicated widget type,
which will make future improvements less messy to implement.

emacs: sanitize dedicated widget action/notify functions

These functions are used as action/notify functions.  That dictates
the appropriate function signatures but even though these functions
are not used for anything else they use incompatible signatures,
forcing the callers to use lambda expressions to deal with these
incompatibilities.

Fix that by adjusting the function signatures to the needs of the
only intended callers.

Two of these functions were defined as commands but because the
interactive form did not return the mandatory arguments, we know
that nobody (successfully) used these as commands.

In one case we move the location of a y-or-n-p prompt.

emacs: use setq instead of set

Commonly `set' is only used if there is no way around it;
i.e. when the variable cannot be known until runtime.

nmbug: notmuch-report: set both background and foreground colors

Whenever setting background color, set also corresponding
foreground color. Don't expect default foreground color to
be #000 (or something close); user may have changed it.

docs: drop deprecated doxygen TCL_SUBST flag

notmuch has no tcl code, and doxygen upstream is deprecating/removing
tcl support anyway:
https://github.com/doxygen/doxygen/commit/48a7afc0caf69857a42b0fe1963db3440cb4000f

Merge branch 'release'

debian: skip gdb based tests on hppa

Revert "emacs: notmuch-search: avoid wiping out buffer-local variables"

This reverts commit f9fbd1ee3bfd679175d88af403752d87a730349f.

Emacs provides a mechanism for avoiding wiping out buffer-local
variables: marking them as "permanent local", which essentially
means "don't wip out the local value when enabling major-mode".

  (put 'the-variable 'permanent-local t)

See (info "(elisp)Creating Buffer-Local").

Whether refreshing the buffer contents should involve re-enable the
mode is a different question, which should not be decided based on
the fact that we want keep the value of some random variable, not
least because some other (e.g. cache) variables are likely expected
to be wiped.

Merge branch 'release'

Commit Debian 3.0 (quilt) metadata

[dgit (9.12) quilt-fixup]

debian: drop debian/patches

These were originally committed by git-debrebase. Unfortunately git
debrebase does not seem to like the notmuch git workflow, so giving up
on it for now.

debian: don't tag debian tag at release is made.

This reflects a change in the debian workflow to use dgit, which does
the tagging for us.  It also leaves room for debian specific fixups.

NEWS: add news for 0.31.3

debian: changelog for 0.31.3-1

version: bump 0.31.3

test/T360-symbol-hiding.sh: trim extra output from readelf

readelf on (at least) ppc64le sometimes generates some extension to
the Ndx name inside '[]'. Remove this output to allow our simple
column based parsing to work.

python/notmuch2: fix exclude tag handling

A typo in Database._create_query lost the exclude_tag names during the
string to utf-8 conversion.

Amended by DB: fixed patch format and updated commit message.

lib/config: delay setting talloc destructor

If Xapian has thrown an exception, it is not safe to invoke the
destructor when freeing the list struct.

(cherry picked from commit 43ba5ed7eca6e9f6433b8c2c2a9d834d4101b92a)

lib: factor out notmuch_database_open* related code to own file

Reduce the size of database.cc, and prepare for extending the database
opening API

test: add regression test for searching with alternate config

Make sure upcoming changes to config handling do not break command
line specification.

lib/config: delay setting talloc destructor

If Xapian has thrown an exception, it is not safe to invoke the
destructor when freeing the list struct.

lib: factor out prefix related code to its own file

Reduce the size of database.cc, and limit the scope of prefix_table,
make sure it's accessed via a well-defined internal API.

lib: factor out feature name related code.

database.cc is uncomfortably large, and some of the static data
structures do not need to be shared as much as they are.

This is a somewhat small piece to factor out, but it will turn out to
be helpful to further refactoring.

test: use keys with group 'test' in T590-libconfig

In a future commit we want to interoperate better with glib KeyFiles,
which need groups for all keys.

Merge tag 'debian/0.31.2-5'

notmuch release 0.31.2-5 for unstable (sid) [dgit]

[dgit distro=debian no-split --quilt=linear]

Commit Debian 3.0 (quilt) metadata

[dgit (9.12) quilt-fixup]

debian: changelog for 0.31.2-5

test/T360-symbol-hiding: use readelf in place of nm

It turns out that using nm -P isn't as portable as hoped. In
particular with some ELF ABIs (e.g. ppc64 ELFv1), the desired symbols
end up in the data section instead of text.

The test is currently only functional on ELF based architectures, so I
think it's legit to depend on readelf instead of nm.

The switch to readelf has the advantage that we can explicitely ask
for all of the symbols with global visibility, rather than grepping
for notmuch. That seems a more robust approach since it will catch any
strangely named global symbols.

Merge branch 'release'

Commit Debian 3.0 (quilt) metadata

[dgit (9.12) quilt-fixup]

debian: changelog for 0.31.2-4

build/docs: move docstring prereq to file targets

Under a sufficiently high level of parallelism [1] there seems to be a
a race condition that allows sphinx-build to start running before the
docstrings are extracted. This change moves the docstring stamp from
the phony targets sphinx-html and sphinx-info to the file targets that
they depend on. I'm not sure why this makes things better, but I am
fairly confident it does not make things worse, and experimentally it
seems to eliminate the race condition.

[1]: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=976934

emacs: avoid binding unnamed commands in keymaps

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.

emacs: do not quote self-quoting t

emacs: use setq-local

It is available since Emacs 24.3 and we require at least Emacs 25.
It makes the variable buffer-local if it isn't always buffer-local
anyway.

emacs: use defvar-local

It is available since Emacs 24.3 and we require at least Emacs 25.

emacs: inline notmuch-split-content-type

This trivial helper function actually made things slightly
*less* readable by adding an unnecessary indirection.

emacs: inline notmuch-documentation-first-line

Inline a simplified version of `notmuch-documentation-first-line'
into its only caller.  The new code snippet differs from the
removed function in that it returns nil instead of the empty string
for symbols that have no function documentation.  That value is
ultimately used as an argument to `concat', which treats nil like
the empty string.  So we can do the logical thing without changing
the behavior.

emacs: remove unnecessary notmuch-tree-button-activate

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: f8bdba37d3f4c877e05e17b5b1c7d2d512106538
   emacs: tree: remove binding for pressing button in message pane

emacs: remove unused notmuch-address-locate-command

We stopped using it in [1: 0e671478].

1: 0e671478c6f37018973392f049979da5e1a8ff99
   emacs: replace use of notmuch-address-message-insinuate

emacs: remove unnecessary notmuch-remove-if-not

We could just have switched to using `cl-remove-if-not' instead,
but the two uses of the *remove-if-not function are pretty strange
to begin with so we refactor to not use any such function at all.

emacs: remove deprecated notmuch-folder command

It has been deprecated for a decade and it's time to let go.

emacs: misc doc-string improvements

emacs: always use elisp quoting style in doc-strings

Emacs doc-strings use neither markdown nor lisp symbol quoting.

emacs: place complete first sentence on first doc-string line

emacs: place only first sentence on first doc-string line

emacs: shorten/replace first sentence of a few doc-strings

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.

emacs: define notmuch-hello-url as a constant

emacs: sanitize function that displays version

Previously it was defined in "notmuch-hello.el" and its name contained
"hello" solely because it replaced an anonymous function that was
mistakenly only bound in `notmuch-hello-mode-map'.  But it makes more
sense to bind it in all notmuch modes and even if we did not change
that aspect it still would make no sense to have "hello" in its name.

emacs: more cleanup since dropping support for Emacs 24

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'.

emacs: remove kludge for Emacs 23 from notmuch-mua-mail

Notmuch requires at least Emacs version 25.

The `return-action' argument was added prior to Emacs 24.1
in 25ca2e61403f97b5a023164f2924d5f8aca2492a.

emacs: fix old bug in notmuch-mua-mail

This fixes a regression introduced in [1: 7e20d264].  If the argument
RETURN-ACTION was non-nil then we should pass along the value of that
argument.  Instead we passed along the constant symbol `return-action'.

1: 7e20d26480553f57d53bd9ec28cae163c1ac91e3
   emacs: Fix mail composition under Emacs 23

emacs: remove redundant notmuch-hello-trim

Use `string-trim', which exists since Emacs 24.4.

emacs: don't fset keymaps

These keymaps are never invoked as commands
so the function definitions serve no purpose.

emacs: add doc-string to notmuch-tree-mode-map

emacs: define notmuch-message-mode-map explicitly

Key bindings should not be defined at the top-level but inside
a `defvar' form.  Doing it at the top-level makes it harder to
reliably customize key bindings.

emacs: silence byte-compiler

debian: upload 0.31.2-3

debian: changelog for 0.31.2-2

debian: run tests in verbose mode

A hopefully temporary change to try and debug some test failures on
autobuilders.