emacs: Improve doc-strings

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

emacs: Use makefile-gmake-mode in Makefile*s

Use `makefile-gmake-mode' instead of `makefile-mode' because the
former also highlights ifdef et al. while the latter does not.

"./Makefile.global" and one "Makefile.local" failed to specify any
major mode at all but doing so is necessary because Emacs does not
automatically figure out that these are Makefiles (of any flavor).

emacs: notmuch-poll: Let the user know we are polling

It is done synchronously and it can take a while,
so we should let the user know what is going on.

emacs: No longer define notmuch-hello-mode-map as a function

It was defined as such for a decade; ever since
a56010ac8b89a2489eee5c78469f05cee85ec858 but there
wasn't a reason to do that then nor is there now.

emacs: Fix some function declarations

emacs: Extend face to window edge again

Since Emacs 27 each face has to be explicitly configured to "extend
to the edge of the window".  Without doing that the face used for
the newline character only has an effect that spans "one character"
(i.e. it looks like there is a single trailing space character).

We don't want that so extend the face in Emacs 27, so that it looks
the same as it did in older Emacs releases.  We have to do this
conditionally, otherwise older Emacsen would choke on it.

emacs: Use one or three lines for 'if' forms

Putting the COND and THEN parts on the same line but ELSE on a
separate line makes it harder to determine if there actually is
an ELSE part.

emacs: Use 'when' instead of 'if' when there is no ELSE part

emacs: Use 'unless' instead of 'when' and 'not'

Also use 'unless' in a few cases where previously 'if' was used with
'not' but without an ELSE part.

emacs: Use 'and' instead of 'when' when the return value matters

Also do so for some 'if' forms that lack an ELSE part.
Even go as far as using 'and' and 'not' instead of 'unless'.

emacs: Only set one variable per setq form

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.

emacs: Closing parenthesis go on the same line

emacs: Fix indentation

emacs: Remove excess empty lines

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.

emacs: Shorten long lines

Emacs: Ensure left-to-right display for message headers

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.

T355: specify hash algorithm explicitly

On some systems (notably, the one shipped with LibreSSL),
default fingerprint digest algorithm is SHA256.

On other systems, users can change default digest algorithm by changing
default_md in /etc/ssl/default_md.

Let's ask openssl to provide us specific algorithm to make the test
more deterministic.

Signed-off-by: Đoàn Trần Công Danh <congdanhqx@gmail.com>

configure: drop check for default xapian backend

Starting from xapian 1.3.5, xapian switched default backend to glass.

From 00cdfe10 (build: drop support for xapian versions less than 1.4,
2020-04-22), we only support xapian 1.4.0+. Effectively, we don't need
to check for default xapian backend anymore.

Further more, from 99a7aac8 (test: drop use of db_ending, 2020-07-29),
our test framework has become independence from default xapian.

Let's drop it.

Signed-off-by: Đoàn Trần Công Danh <congdanhqx@gmail.com>

configure: check for pytest with python -m pytest

On different distro, pytest is suffixed with different patterns.

On the other hand, `python3-pytest' could be invoked correctly,
via `python3 -m pytest', the latter is used by our tests, now.

Switch to `$python -m pytest` to fix address all incompatible naming.

Signed-off-by: Đoàn Trần Công Danh <congdanhqx@gmail.com>

test: regression tests for n_indexopts_{get,set}_decrypt_policy

The main criteria is that they don't crash. Working with a closed
database is a bonus.

test: regression test for traversing config list with closed db

Also mention error return in API docs

test: regression test for n_d_get_config_list on closed db.

Exception is caught.

test: regression test for n_directory_{get,set}_mtime

The mtime is cached, so closing the db is not a problem. Writing the
mtime throws an exception, which is caught.

lib: fix return value for n_directory_delete

Falling out of the catch meant the error return was lost

test: known broken test for n_directory_delete with closed db.

There is a return value bug in notmuch_directory_delete that is hiding
the exception.

lib: catch exceptions in n_directory_get_child_files

Also clarify API in error case.

test: add known broken test for n_directory_get_child_files

This is a clone of the one for get_child_directories

lib: catch exceptions in n_directory_get_child_directories

Also clarify API in error case.

test: add known broken test for n_directory_get_child_directories

Start a new test file (for the notmuch_directory_* API group) to hold
this test.

test: regression test for n_m_get_filenames

Closing the database after the iterator is created is not a problem.

test: split header for lib-message tests.

This allows finer control over when to close the database.

test: add regression test for n_messages_collect_tags

Also test n_messages_destroy.

lib: return NULL from n_d_get_default_indexopts on error

This is a rare and probably serious programming error, so better not
to silently return a default value.

build: upload html docs as part of release process

Use a URL https://notmuchmail.org/doc/latest to leave room for a
future more ambitious scheme deploying multiple versions.

This also forces the html docs to built as part of the release
process. In the future this should be updated to tolerate generating a
release without sphinx installed. This needs a new target analogous to
build-info and build-man that does nothing if sphinx is not installed.

test: drop use of db_ending

This will allow the dropping of the test for the default ending from
configure.

test: drop NOTMUCH_DEFAULT_XAPIAN_BACKEND from T360-symbol-test

Inspired by the suggestion of

         id:20200727154108.16269-3-congdanhqx@gmail.com

to drop the configuration test for the default backend. This version
is hopefully robust against backend changes.

test: destroy thread from closed database

Check for (non)-crash.

test: regression test for n_thread_get_tags

Code is taken from the API docs, with the twist that the underlying
database is closed. Not crashing is the main point.

test: add regression tests for oldest and newest dates

These are strictly to watch for crashes, so don't be too fussy about
the actual timestamps.

test: add regression tests for n_t_get_{authors, subject}

This is returning explicitely cached data, so no database access is needed.

test: add regression test for n_t_get_messages

This is similar to the case of toplevel messages. Currently everything
is cached, so no database access is necessary. This might change in
the future, but it should not crash in either case.

test: add regression tests for n_thread_get_toplevel_messages

Include a test for the previously omitted non-trivial code path for
notmuch_thread_get_replies.

test: add regression test for n_thread_get_total_{messages,files}

This is returning cached info, so does not need to access the (closed)
database.

test: regression test for n_t_get_thread_id

This is just cached data, so as long as we don't prematurely free
anything, it should be fine.

test: regression test for notmuch_query_destroy

As with other void API entries, not crashing counts as success.

test: regression tests for n_q_count_{messages, threads}

At least these exceptions are caught.

test: regression test for n_q_search_messages

Exception handling matches notmuch_query_search_threads, at least for
this case.

test: regression test for n_q_search_threads

At least this exception is caught.

test: add regression test for n_q_add_tag_exclude

This relies on the change to not tear down the auxilary Xapian
objects, in particular the query parser, when the database is closed.

test: regression test for n_q_{set, get}_sort

We just want to make sure accessing the query owned by a closed db
does not cause a crash.

test: regression test for set_omit_excluded

test: regression test for notmuch_query_get_database

Current functionality is too trivial to really justify a test, but
it's simpler just to test the complete API.

test: add regression test for n_q_{create,_get_query_string}

Start a new file of tests, to keep to the (emerging) scheme of one
notmuch_foo group per file

test: move notmuch_message_* tests to their own file

This is for consistency with the recently added tests for
notmuch_database_*.

lib: replace use of static_cast for writable databases

static_cast is a bit tricky to understand and error prone, so add a
second pointer to (potentially the same) Xapian database object that
we know has the right subclass.

lib: encapsulate the use of notmuch_database_t field 'mode'

The plan is to change the underlying representation.

lib: drop two gratuitous assignments to database mode

I'm not sure what the point of modifying that right before destroying
the object is. In a future commit I want to remove that element of the
object, so simplify that task.

test: Explicitly state that we want to sign with sender

Since Emacs 27 'mml-secure-epg-sign' errors out if we don't opt-in to
signing as the sender using 'mml-secure-openpgp-sign-with-sender'.

test: Remove misguided emacs testing utilities

The goal of this abstraction was to save space.  But that failed as
the result actually was that four trivial lines got replace with 15
fairly complicated lines.  The opposite of what it was supposed to
do.

Also it made it harder to come up with the fix in the previous commit;
simply grepping for the relevant symbols did not work because they get
constructed at run-time instead of appearing in the source file.

test: Deal with Emacs 27 switching to lexical scope by default

Starting with Emacs 27 undeclared variables in evaluated interactive
code uses lexical scope.  This includes code passed with '--eval' as
we do in the Emacs tests, which also happen to assume dynamic scope.

- This can affect variables defined by libraries that we use.  We
  let-bind such variables to change the behavior of functions which we
  then call with these bindings in effect.  If these libraries are not
  loaded beforehand, then the bindings are lexical and fail to have
  the effect we intended.

  At this time only 'smtpmail' has to be loaded explicitly (for the
  variables let-bound in emacs_deliver_message and emacs_fcc_message).

  'message' doesn't have to be loaded explicitly, because loading
  'notmuch' (in 'run_emacs') already takes care of that, indirectly.

- Our own testing-only variables also have to be declared explicitly.
  We should have done that anyway, but because of how and where these
  variables are used it was very easy to overlook that (i.e. it isn't
  something the byte-compiler ever looks at).  Not so in Emacs 27
  anymore; here this oversight caused four tests to fail.

  The numeric values of these variables get incremented by functions
  that we add to hooks that are run by many tests, not just the tests
  where we actually inspect the value and therefore take care to let-
  bind the values to 0 before we begin.  The global values therefore
  have to be numeric values as well.  I have chosen -100 instead of 0
  as the default in case someone writes a test that inspects the value
  but forgets to let-bind the value.  I hope that the unusual negative
  value that one is going to see in such a case will help debugging
  the issue.

gitignore: Ignore generated sphinx.config

test: add known broken test for n_d_get_default_indexopts

Xapian exceptions are swallowed and turned into default return value.

lib: fix error return bug with n_d_set_config.

The catch block either needs to return, or the function needs to
return "status". Choose the latter for consistency with
n_d_get_config.

test: add known broken test for n_d_set_config

Error status is currently lost.

test: add regression test for n_d_get_config

Xapian exceptions seem to handled OK, at least for this case.

lib: add regresion test for n_d_get_all_tags

Existing error handling seems adequate, if not ideal.

lib: add regression test for n_d_find_message_by_filename

At least this Xapian exception is caught. Make sure it stays that way.

lib: rename _n_d_create to _n_d_find_or_create

The error message and name were confusing when called in some "read
only" context.

test: add known broken test for notmuch_database_remove_message

The current error message is a bit confusing; fix in next commit.

lib: convert relative filenames to absolute in n_d_index_file

The API docs promise to handle relative filenames, but the code did
not do it.

Also check for files outside the mail root, as implied by the API
description.

This fixes the bug reported at

     id:87sgdqo0rz.fsf@tethera.net

test: add known broken test for indexing relative path

The current code seems to look for the path relative to the current
working directory, rather than the mail store root.

test: regression test for n_d_index_file closed db

Current exception handling seems OK, at least for this case.

test: add regression test for n_d_get_directory

At least this exception is already handled correctly.

test: regression test for n_d_get_revision

This function only accesses data cached by notmuch, so being closed is
not a problem.

test: add regression test for n_d_{begin,end}_atomic

Xapian currently succeeds to begin/end a transaction on a closed database,
or at least does not throw an exception. Make the test robust against
this changing.

test: regression test for n_d_upgrade

The logic is that if it's acceptable to return SUCCESS for read only
database, it's acceptable for a closed one.

lib/n_d_needs_upgrade: handle error return from n_d_get_version

Also clarify documentation of error return from n_d_needs_upgrade.

test: add known broken test for n_d_needs_upgrade

It's a bit arbitrary which value to return for errors, but the same
argument as for read only databases applies for errors.

test: add regression tests for notmuch database destroy

Either an open or closed database should be ok to destroy

test: regression test for closing a closed database

This does not currently throw an error, and it should stay that way.

lib/n_d_get_version: catch exceptions and clarify the API

notmuch_database_get_version previously returned 0 on some errors, but
did not document this. Luckily 0 is not a valid database version.

lib: move deallocation of memory from n_d_close to n_d_destroy

In order to mimic the "best effort" API of Xapian to provide
information from a closed database when possible, do not
destroy the Xapian database object too early.

Because the pointer to a Xapian database is no longer nulled on close,
introduce a flag to track whether the notmuch database is open or not.

test: add known broken test for n_d_get_version on closed db

This should not crash, but it does currently.

test: regression tests for n_d_status_string and n_d_get_path

These do not crash on a closed database, and we want to keep it that
way.

Start a new file of tests as T560-lib-error was starting to get unwieldy.

lib: fix exception messages for n_m_message_*

The original generic handler had an extra '%s' in the format
string. Update tests that failed to catch this because the template to
print status strings checked 'stat', which was not set.

test: sanitize line numbers in exception reports

Prevent test suite churn when reported line numbers change.

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

lib: fix return value for n_m_reindex

Also update the documentation for the behaviour of n_m_get_thread_id
that this fix relies on.

test: add known broken test for n_m_reindex on closed db

This is another case where the code should not call INTERNAL_ERROR.

test: regression for retrieving closed db from message

This is actually one of the few potentially useful things you can do
with a message belonging to a closed database, since in principle you
could re-open the database.

test: regression test for destroying message with closed db

This should be fine because the message belongs to the
database (talloc context wise).

test: regression tests of n_m_freeze and n_m_thaw on closed db

Neither of these accesses the database, so should be safe. Add the
tests to catch any changes in exception throwing.

lib: handle xapian exception in n_m_remove_all_tags

At least the exception we already catch should be reported properly.

test: add broken test for n_m_remove_all_tags

The Xapian exception is actually caught here, but the NULL return is
not dealt with properly.

test: add regression test for n_m_maildir_flags_to_tags

This function currently catches at least the obvious Xapian exceptions
and we want to keep it that way.

cli/new: replace newly deprecated n_m_has_maildir_flag

Boolean return values have no out-of-band-values to signal errors. The
change here is that a (somewhat unlikely) fatal error after indexing
will now be caught.

lib: add notmuch_message_has_maildir_flag_st

Initially the new function is mainly tested indirectly via the
wrapper.

test: add regression test for notmuch_message_has_maildir_flag

This passes the NULL return inside _ensure_maildir_flags does not
break anything. Probably this should be handled more explicitely.

configure: replace multiple redirects with redirected block

This belatedly implements Tomi's suggestion from

     id:m25zaukv6u.fsf@guru.guru-group.fi

bindings/ruby: replacy use of deprecated notmuch_message_get_flag

Depending on the flag, this actually can return an errror, so raise a
ruby exception if so.