doc/emacs: define and use emacsvar and emacscmd markup

This makes it easier to navigate the merged index of all of the
notmuch documentation.

doc: do not generate python module index

This currently seems unhelpful, and not generating it removes if from
the navigation bar, which prevents mis-clicking.

doc: drop module index from ToC

There is only one module listed, so the index is not useful.

doc: retitle notmuch-emacs manual

This makes the HTML TOC read more naturally. Add a label to make cross
referencing easier.

doc: reorganize sphinx toctree

This mainly affects the html output (although users generating epub or
pdf would also notice a change). The goal is twofold: make the TOC a
bit friendler and easier to navigate by introducing some hierarchy,
and allow links for nmbug and notmuch-setup.

doc: improve config item labels in info output

Commit 306b7028d added the nmconfig role / directive. Unfortunately
the default of using the directive name in texinfo output is pretty
ugly, so attempt to make it more human readable by passing `objname`
to add_object_type invocation.

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.

emacs/show: introduce notmuch-show-height-limit

Analogous to notmuch-show-depth-limit, it requires a bit more
calculation, but that cost seems dominated by the rendering cost.

emacs/show: obey notmuch-show-max-text-part-size for part 0

This parameter was originally introduced to hide large attachements
that happened to be text/plain. From a performance point of view,
there is no reason not to also hide large message bodies.

emacs/show: optionally insert bodies of "deep messages" lazily

This leverages the machinery already there to insert buttons for
attachments.

A potential use-case is browsing the top layers of the tree to decide
which of the lower subtrees to read.

perf-test/emacs: test showing longish threads

This particular thread takes about 100 times longer to display in
emacs than on the command line.

The parameter notmuch-show-max-text-part-size exists, but is currently
ineffective for this task because it only hides attachments, not
part 0.

In future commits, the parameter notmuch-show-{depth,height}-limit
will trigger a similar kind of hiding for bodies as
n-s-m-text-part-size already does for attachments.

debian: add git as a build-dependency, for the test suite

This is needed to run (and test) notmuch-git.

CLI/git: add --format-version argument to init subcommand

This is primarily intended to support testing upward compatibility
with legacy repos.

CL/git: add format version 1

The original nmbug format (now called version 0) creates 1
subdirectory of 'tags/' per message. This causes problems for more
than (roughly) 100k messages.

Version 1 introduces 2 layers of hashed directories. This scheme was
chose to balance the number of subdirectories with the number of extra
directories (and git objects) created via hashing.

This should be upward compatible in the sense that old repositories
will continue to work with the updated notmuch-git.

CLI/git: replace most mentions of nmbug

Particularly in help messages, nmbug is confusing for users who may
have never heard of it.

test: known broken test for top level .notmuch in split configs

In split configurations there is no special significance to a top
level directory called .notmuch in the mail root. Users should
therefore be able to have mail stored underneath it.

bindings/python-cffi: fix docstring

the method Database.get_message does exist any more (if it ever
did). This makes the docstring unhelpful as an example.

test: add new corpus of duplicate messages

This corpus will be used to test a new --duplicate option for notmuch-show

test: define and use notmuch_sexp_*_sanitize functions

These are based on the equivalent functions for json. Like those,
these are pretty simple-minded, and don't really understand the
syntax.

test: use notmuch_json_show_sanitize more places

This makes the tests more robust against changing output formats, by
allowing us to centralize fixes in the sanitization function. It is
not appropriate for all cases, in particular it is unneeded when using
test_json_nodes, and unhelpful when testing filenames.

doc: replace symlink with copies for nmbug, notmuch-setup

Previously only man page aliases were being added as symlinks.  The
addition to man_pages in conf.py automatically propagates to the list
of generated info pages.

Installation of the new pages is handled by existing recipes.

emacs: mark notmuch-query.el as obsolete

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.

lib/sexp: add parameter expansion for regex and wildcard

Fix the bug reported at [1].

The parameter expansion for regex and wildcard modifiers has to be
done a bit differently, because their arguments are not s-expressions
defining complete Xapian queries.

[1]: id:87o7yxqxy6.fsf@code.pm

test/sexp: add known broken tests for macro param inside rx/wildcard

These tests replicate the problem reported by Eric Colson [1] (for the
regex case).

[1]: id:87o7yxqxy6.fsf@code.pm

make git ignore new build products

nmbug and notmuch-git are new build products. Make git ignore them just
like other build products.

Signed-off-by: Michael J Gruber <git@grubix.eu>

doc/sexp: document range queries.

Give examples for date fields, as these are commonly useful for user
queries.

lib/sexp: allow * as alias for "" in range searches.

It can be tedious to use "" inside of a string, e.g. in a shell script.

lib/sexp: special case "" as an argument in lastmod ranges.

Support this syntax for constincy with (data from to) ranges.

test/sexp: one sided range searches.

The date range parsing machinery already knows how to do something
appropriate with an empty string, but the lastmod parsing blindly
tries to parse each atom as a number.

lib: check for writable db in n_m_tags_maildir_flags

The database needs to be writable because the list of stored file
names will change in general.

lib: add NOTMUCH_STATUS_CLOSED_DATABASE, use in _n_d_ensure_writable

In order for a database to actually be writeable, it must be the case that it
is open, not just the correct type of Xapian object. By explicitely
checking, we are able to provide better error reporting, in particular
for the previously broken test in T566-lib-message.

lib: Add missing private status values.

These were missed when the corresponding status codes were added.

lib/tag: handle NULL argument to notmuch_tags_valid

Make the behaviour when passed NULL consistent with
notmuch_filenames_valid. The library already passes the result of
notmuch_message_get_tags without checking for NULL, so it should be
handled.

test: add known broken test for notmuch_tags_valid (NULL)

This should return false, but currently segfaults.

Start a new file for tags library API related tests. This is maybe
overkill, but new C boilerplate which doesn't corrupt the database is
needed anyway.

test: error handling for n_m_tags_to_maildir_flags

The closed database case should fail gracefully, but currently it
segfaults.

test: error handling in _n_message_{add,remove}_filename

Use a closed database to force throwing a Xapian exception. Leave the
check vague to accomodate a potential explicit check for open database.

lib/message: check return status from _n_m_add_{path,folder}_terms

Mainly to propagate information about Xapian exceptions.

lib/message: check return status of _n_m_{add,remove}_term

Xapian exceptions are not something that can be ignored, in general.

lib: define macro NODISCARD

In either C++17 (or later) mode, or when running cppcheck, this can be
used to selectively generate warnings about discarded return values.

lib/message: drop _notmuch_message_get_thread_id_only

This function has been unused since commit 4083fd8.

test: _notmuch_message_remove_term catches exceptions.

Unfortunately we can't differentiate between the two distinct error
conditions for Document::remove_term.

lib/message: catch exceptions in _n_m_add_term

Some code movement is needed to make sure the cache is only
invalidated when the Xapian operation succeeds.

test: define test_private_C

When testing error handling, it is sometimes difficult to cover a
particular error path deterministically. Introduce a test function to
allow calling lower level functions directly.

CLI: set NOTMUCH_CONFIG in hooks.

This addresses a bug report / feature request of Uwe Kleine-König. The
assumption is that we always load a config file in the CLI (i.e. we
never pass "" as the config file argument to
notmuch_database_open_with_config).

[1]: id:8baa58c3-7ab9-ec03-1bbd-28aa5be838f2@kleine-koenig.org

test: add known broken tests for setting NOTMUCH_CONFIG in hooks

Setting this according to --config was requested by Uwe
Kleine-König. There are some other ways that the configuration file
might be found in current notmuch, so check those as well.

As a bonus, fix a bug in the hook tests that left NOTMUCH_CONFIG set
even though a config file was provided via NOTMUCH_PROFILE.

[1]: id:8baa58c3-7ab9-ec03-1bbd-28aa5be838f2@kleine-koenig.org

debian: install notmuch-git

Use a separate binary package to avoid dragging in dependencies on
python and git for those that do not want them.

CLI/git: add safety checks for checkout and commit

Commits or checkouts that modify a large fraction of the messages in
the database should be relatively rare (and in some automated process,
probably non-existent). For initial setup, where such operations are
expected, the user can pass --force.

CLI/git: support configuration for repo location / prefix

This is probably more convenient than always passing a command line
argument.

Use notmuch-config for consistency with other notmuch CLI tools.

Now that there is something relevant in the config files, test the
--config option.

CLI/git: change defaults for repo and prefix

The previous defaults were not suitable for personal (i.e. not
bugtracking for notmuch development) use.

Provide two ways for the user to select nmbug compatible defaults;
command line argument and checking the name of the script.

doc/notmuch-git: initial documentation

This is mainly derived from the various help outputs from the script,
with some massaging of markup and addition of links.

CLI/git: cache git indices

If the private index file matches a previously known revision of the
database, we can update the index incrementally using the recorded
lastmod counter. This is typically much faster than a full update,
although it could be slower in the case of large changes to the
database.

The "git-read-tree HEAD" is also a bottleneck, but unfortunately
sometimes is needed. Cache the index checksum and hash to reduce the
number of times the operation is run. The overall design is a
simplified version of the PrivateIndex class.

CLI/git: add @timed decorator, time a few functions

Perf will show which binaries are using the CPU cycles, and standard
python profilers will show which python functions, but neither is
great at finding which call to an external binary is taking time, or
locating I/O hotspots.

CLI/git: replace enumeration of tags with sexp query.

Unlike the (current) infix query parser provided by Xapian, the
notmuch specific sexp query parser supports prefixed wildcard queries,
so use those. In addition to being somewhat faster, this avoids
needing to escape all of the user's tags to pass via the shell.

test/git: add known broken test for tag with quotes.

There is current insufficient sanitization and/or escaping of tag names
internally in notmuch-git.

CLI/git: suppress warnings about initial branch name

The canonical nmbug repository still uses "master" as the main branch
name, so defer any potential switch away from that name.

CLI/git: rename environment variables.

Although the code required to support both new and old environment
variables is small, it complicates the semantics of configuration, and
make the documentation harder to follow.

test: initial tests for notmuch-git

Exercise the main functionality of notmuch-git.  add_git_repos() will
hopefully be simplifed when an init subcommand is added.

CLI/git: Add an 'init' command

For folks that want to start versioning a new tag-space, instead of
cloning one that someone else has already started.

The empty-blob hash-object call avoids errors like:

  $ nmbug commit
  error: invalid object 100644 e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 for
'tags/...'
  fatal: git-write-tree: error building trees
  'git HASH(0x9ef3eb8) write-tree' exited with nonzero value

David Bremner suggested [1]:

  $ git hash-object -w /dev/null

instead of my Python version of:

  $ git hash-object -w --stdin <&-

but I expect that closing stdin is more portable than the /dev/null
path (which doesn't exist on Windows, for example).

The --bare init and use of NMBGIT as the work tree (what could go
wrong with an empty commit?) are suggestions from Michal Sojka [2].

[1]: id:87y4vu6uvf.fsf@maritornes.cs.unb.ca
     http://thread.gmane.org/gmane.mail.notmuch.general/18626/focus=18720
[2]: id:87a93a5or2.fsf@resox.2x.cz
     http://thread.gmane.org/gmane.mail.notmuch.general/19495/focus=19767

CLI/git: make existance of config branch optional on clone

This branch is actually only used by an associated
utility (notmuch-report), and notmuch-git works fine without it.

notmuch-git: add --git-dir, --tag-prefix arguments

It is often more convenient to use command line arguments than
environment variables.

CLI/git: drop support for python < 3.2

Debian stable had python 3.4.2 3 releases ago (approximately 6 years
ago), so attempting to keep track of the changes in python is probably
no longer worthwhile. We already require python 3.5 for the
python-cffi bindings (although those are not yet used in notmuch-git).

nmbug: promote to user tool "notmuch-git"

Initially just a rename, and drop the --version argument that clashes
with the global notmuch --version argument.

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.

emacs: Make notmuch-show-next-thread return nil on failure

Having notmuch-show-next-thread return non-nil on success and nil on
failure makes it easier for users to interact with notmuch via elisp.

This commit changes notmuch-search-show-thread too since the return
value of notmuch-show-next-thread depends on notmuch-search-show-thread.

Amended by db: fix whitespace in T450-emacs-show

CLI: document handling of --config for external commands

Create a section of the notmuch(1) manpage to have some place to put
this documentation.

CLI: pass --config to external commands via NOTMUCH_CONFIG.

This makes `notmuch --config foo external-subcommand` work
consistently with the built in subcommands.

test: initial tests for external commands

The main goal is to test the setting of NOTMUCH_CONFIG, but also
include a basic sanity test for execing scripts.

CLI: mention sexp-queries in help topics, alphabetize

There does not seem to be an easy way to automate maintaining this
list, but new topics are not added very often.

CLI: simplify help command

This will allow "notmuch help" to work for arbitrary external commands
and for any added non-command topics (such as notmuch-sexp-queries).

emacs: change where notmuch-mua-mail moves point

Move point to the position that makes the most sense instead of always
moving point to the TO.  This is useful when TO/SUBJECT are passed as
argument.

Amended by db: move news item to UNRELEASED.

emacs: notmuch-show-header-line: allow format strings and functions

If a string value is assigned to notmuch-show-header-line, it's used
as a format string to be passed passed to format-spec with `%s`
substituted by the message's subject.  If a function is given, it's
called with the subject as argument, and its return value used as
header line.

As before, t means displaying the subject and nil not using any header
line.

Signed-off-by: jao <jao@gnu.org>
Amended-by: db, docstring spelling fix

test: replace deprecated use of notmuch_database_create

Like notmuch_database_open, we need to conditionally print the error
message.

test: replace deprecated use of notmuch_database_open

This is a bit more involved than replacing the use of
notmuch_database_open_verbose, as we have to effectively inline the
definition of notmuch_database_open.

test: replace deprecated use of notmuch_database_open_verbose

We need to do it some day, and it is a bit annoying to read
deprecation messages in broken tests.

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.

test: make T450 independent of application/octet-stream interpretation

The actual content type of `application/octet-stream` is up to content
type detection of the reader, and thus may not be stable across
implementations or versions. This showed up when

fd46fc19 ("emacs:  document/defcustom notmuch-multipart/alternative-discouraged", 2022-05-14)

introduced a test for omitting a part of type `text/html` because it
expected a part of type `application/octet-stream` to remain in place,
i.e. a part of "unstable type". In particular, tests with `fd46fc19`
would succeed on RHEL/EPEL but fail on all current Fedoras with

```
 FAIL   multipart/alternative hides html by default
--- T450-emacs-show.16.notmuch-show-multipart-alternative 2022-05-26 15:34:42.100557244 +0000
+++ T450-emacs-show.16.OUTPUT 2022-05-26 15:34:42.102557207 +0000
@@ -24,7 +24,7 @@
 uses 64 as the
 buffer size.
 [ text/html (hidden) ]
-[ 0001-Deal-with-situation-where-sysconf-_SC_GETPW_R_SIZE_M.patch: application/octet-stream (as text/x-diff) ]
+[ 0001-Deal-with-situation-where-sysconf-_SC_GETPW_R_SIZE_M.patch: application/octet-stream (as text/x-patch) ]
 From e3bc4bbd7b9d0d086816ab5f8f2d6ffea1dd3ea4 Mon Sep 17 00:00:00 2001
 From: Alexander Botero-Lowry <alex.boterolowry@gmail.com>
 Date: Tue, 17 Nov 2009 11:30:39 -0800
```

due to the different type detected.

Fix this by giving that message a specicific type of `text/x-diff` in
the test corpus, and adjust all affected test outputs.

Signed-off-by: Michael J Gruber <git@grubix.eu>
Amended-by: db, fix some trailing whitespace

Merge branch 'release'

lib/message: use false from stdbool.h

As far as I know, this is just a style / consistency thing, unless
notmuch code starts defining FALSE inconsistently with false.

merge uninitialized field fix from release

lib: fix uninitialized field in message objects.

Initially reported by Eliza Vasquez [1] (via valgrind).

[1]: id:87o7zxj086.fsf@eliza.

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.

doc: define and use semantic markup for configuration items

This makes sure each configuration item is cross referenceable without
extra markup, and also adds index entries.

emacs/reply: restrict what mime types are inlined by default

Apply the previously factored-out function used by notmuch-show.

emacs: factor out calculation of mm-inline-override-types

The intended use case of this new function is to make reply behaviour
track that of show with respect to attachments.

Also fix the glob (which worked by fluke) into the documented regexp.

test: add known broken test for inlining in emacs/reply

The same mitigation already applied for show should also be applied
for reply

test/emacs: add regression test for display of tar attachments

These should continue to display as buttons by default, even as we
update the handling for reply.

test: start corpus for attachments

Initially these are to test the emacs frontend.

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.

doc/sexp-queries: be more consistent about ending example text

Most, but not all of the the explanatory texts already end in
'.'. This makes the remainder match.

doc/sexp-queries: fix example

Update the explanatory text to match the query.

doc/sexp-queries: escape @ in non-verbatim text

This prevents sphinx-doc from creating spurious mailto: links. Thanks
to Jakub Wilk for telling me about the fix.

Merge branch 'release'

debian: changelog for 0.36-1

NEWS: set release date

version: bump to 0.36

Merge branch 'release'

NEWS: user visible changes for 0.36

NEWS: fix location for notmuch-web

It actually lives under 'devel/', not 'contrib/`.

configure: avoid warning with -Wall

7228fe68 ("configure: restructure gmime cert validity checker code",
2022-04-09) restructured generated C code to repurpose it later on. This
put usage of `validity` within an `#if`, resulting in an "unused
warning" if that `#if` is not executed.

Put the variable declariation inside the same if branch and, thus,  quel
the warning.

Signed-off-by: Michael J Gruber <git@grubix.eu>

debian: changelog for 0.36~rc1-1