debian: update debian/NEWS and debian/changelog

Plagiarize my upstream summary for debian, and mention the new
upgrade.

version: bump to 0.19

NEWS: deprecate notmuch deliver

notmuch-deliver has no commits for about 2.5 years. notmuch-insert has
all the features that deliver does, and as far as I understand the
error handling has now caught up.

NEWS: add short overview section

I decided to err on the side of brevity, since the details are just
below.

News for mark read handling

amended by db: capitalized notmuch.

doc: Minor fixes related to notmuch-address

- Add notmuch-address to HTML index
- Remove extra '*'

NEWS: notmuch address

NEWS: functions in emacs notmuch-show-stash-mlarchive-link-alist

News for emacs: allow functions in
notmuch-show-stash-mlarchive-link-alist.

NEWS: notmuch insert, search updates

News for

- cli: add support for notmuch search --duplicate=N with --output=messages
- cli/insert: add post-insert hook
- cli/insert: require succesful message indexing for success statu

NEWS: Database version 3, API improvements, and ghost messages

debian: bump standards version

bump version to 0.19~rc2

emacs: show: document the mark unread defcustom function

cli: notmuch address option defaults update

When no --output option were given, change default to display senders
only.

When only --count option is given, display senders (in contrary to not
displaying anything).

Document that --count with --sort=**order** is not supported option
combination.

Clean up some whitespace in the documentation.

One test updated to have --output=count without sender nor recipient
output option.

doc: whitespace cleanup

Changed one tab in doc/man1/notmuch-show.rst to 8 spaces.

Removed one leading tab in doc/man5/notmuch-hooks.rst to make
the SYNOPSIS style consistent with other pages.

News for dump/writelock change

debian: bump date in changelog.

It looks a bit riduculous to have a September date there.

lib: bump LIBNOTMUCH_MAJOR_VERSION to 4

This should have been done at the same time as the SONAME bump.

version: update to 0.19~rc1

Sync NEWS debian/changelog at the same time, although in those cases it's a downgrade.

doc: add notmuch-address.rst to sphinx config

This is needed so that the rst docs are converted to man and info
pages.

cli: address: Add --output=count

This output prints how many times was each address encountered during
search.

cli: address: Do not output duplicate addresses

This filters out duplicate addresses from address command output.

It also also adds tests for the address command.

The code here is an extended version of a patch from Jani Nikula.

cli: search: Convert --output to keyword argument

Now, when address related outputs are in a separate command, it makes
no sense to combine multiple --output options in search command line.
Using switch statement to handle different outputs is more readable
than a series of if statements.

cli: Introduce "notmuch address" command

This moves address-related functionality from search command to the
new address command. The implementation shares almost all code and
some command line options.

Options --offset and --limit were intentionally not included in the
address command, because they refer to messages numbers, which users
do not see in the output. This could confuse users because, for
example, they could see more addresses in the output that what was
specified with --limit. This functionality can be correctly
reimplemented for address subcommand later.

Also useless values of --exclude flag were not included in the address
command.

This was inspired by a patch from Jani Nikula.

cli: add support for hierarchical command line option arrays

NOTMUCH_OPT_INHERIT expects a notmuch_opt_desc_t * pointer in
output_var.

The "Unrecognized option" message was moved out of parse_option() to
not be emitted twice or when parsing a non-inherited option.

cli: search: Split notmuch_search_command to smaller functions

In a subsequent commit, these functions will be used to share some
functionality between search and address commands.

cli: search: Convert ctx. to ctx->

In the next commit, notmuch_search_command will be refactored to
several smaller functions. In order to simplify the next commit to
verbatim move of several lines to new functions with search_context_t*
argument, we convert all references to this structure to pointer
dereferences. To do so we rename the context variable and use the
original name ctx as the pointer to the renamed structure.

cli: search: Move more variables into search_context_t

In order to share some command line options between search and address
subcommands we need to add corresponding variables to the context
structure. While we are at it, we also add notmuch_database_t to unify
parameters of all do_search_* functions and to simplify subsequent
commits.

Otherwise, there are no functional changes.

cli: search: Rename options to context

In the next commit the options structure will be extended by
non-option variables. Therefore we need a more generic name.

Just text replacement, no other changes.

devel: man-to-mdwn.pl: add GPLv3+ notice to manpages.mdwn

Make the generated head manual page (in the notmuchmail wiki)
display the licence information the whole notmuch software is licenced
under.

devel: make man-to-mdwn.pl to work with generated manual pages

The new manual pages converted from rst using sphinx or rst2man
has somewhat different syntax. man-to-mdwn.pl is now adjusted
to produce even better output from this syntax. The changes also
include using utf-8 locale (e.g. for tables and generated hypens)
and and quite a few bugs fixes.
This tool still produces better results than just using the
html pages generated using sphinx / rst2html. For example those
tools don't create inter-page hyperlinks -- and the preformatted
pages written by man-to-mdwn.pl just works well with manual page
content.

test: Make gen-threads work with python3

python3 doesn't allow dictionaries to be initialized with non-string
keywords. This presents problems on systems in which "python" means
"python3". We instead initalize the dictionary using the dict
comprehension and then update it with the values from the tree. This
will work with both python2 and python3.

test: add tests for --output=messages --duplicate=N

Basic smoke tests for the feature, nothing fancy.

cli: add support for notmuch search --duplicate=N with --output=messages

Print the message IDs of all messages matching the search terms that
have at least N files associated with them.

configure: move make {,install} instructions to the end

There was theorical possibility that writing the config files could
have skipped (by interruption) after the instructions how to make
notmuch was printed out.

cli: search: Add --output={sender,recipients}

The new outputs allow printing senders, recipients or both of matching
messages. To print both, the user can use --output=sender and
--output=recipients simultaneously.

Currently, the same address can appear multiple times in the output.
The next commit will change this. For this reason, tests are
introduced there.

We use mailbox_t rather than InternetAddressMailbox because we will
need to extend it in a following commit.

This code is based on a patch from Jani Nikula.

cli: search: Convert --output to keyword-flag argument

This converts "notmuch search" to use the recently introduced
keyword-flag argument parser. At this point, it only makes the code
slightly less readable but following commits that add new --output
keywords will profit from this.

cli: Add support for parsing keyword-flag arguments

This allows having multiple --foo=bar --foo=baz options on the command
line, with the corresponding values OR'd together.

[Test added by Michal Sojka]

cli: search: Refactor passing of command line options

Many functions that implement the search command need to access command
line options. Instead of passing each option in a separate variable, put
them in a structure and pass only this structure.

This will become handy in the following commits.

NEWS: Improved `q` binding.

emacs: Improve the behaviour of the 'q' binding.

When a user hits 'q' in a notmuch buffer, kill the buffer only if
there are no other windows currently showing it.

test: use LDFLAGS in test/Makefile.local

Apparently the test binaries are built with minimal LDFLAGS, only
adding dependency specific LDFLAGS as needed. However because some of
the test binaries incorporate notmuch object files, it is necessary to
use the same link flags as notmuch. For example user provided
CFLAGS/CXXFLAGS/LDFLAGS with -fsanitize=undefined fails to build the
test binaries if the flags differ.

test: add simple tests for post-insert hook

Most of the existing tests for pre/post-new hook don't seem to apply.

cli/insert: add post-insert hook

The post-new hook might no longer be needed or run very often if
notmuch insert is being used. Therefore a post-insert hook is needed
(arguably pre-insert not so much, so don't add one). Also add the
--no-hooks option to skip hooks.

gitignore: ignore sh.config and doc/config.dox

cli: cast timeval fields to long for format

This hides platform differences between struct timeval field types.

emacs: notmuch-jump.el should provide.

To ease loading, notmuch-jump.el should provide 'notmuch-jump.

lib: Remove unnecessary thread linking steps when using ghost messages

Previously, it was necessary to link new messages to children to work
around some (though not all) problems with the old metadata-based
approach to stored thread IDs.  With ghost messages, this is no longer
necessary, so don't bother with child linking when ghost messages are
in use.

test: Test upgrade to ghost messages feature

lib: Enable ghost messages feature

This fixes the broken thread order test.

lib: Implement upgrade to ghost messages feature

Somehow this is the first upgrade pass that actually does *any* error
checking, so this also adds the bit of necessary infrastructure to
handle that.

lib: Implement ghost-based thread linking

This updates the thread linking code to use ghost messages instead of
user metadata to link messages into threads.

In contrast with the old approach, this is actually correct.
Previously, thread merging updated only the thread IDs of message
documents, not thread IDs stored in user metadata.  As originally
diagnosed by Mark Walters [1] and as demonstrated by the broken
T260-thread-order test, this can cause notmuch to fail to link
messages even though they're in the same thread.  In principle the old
approach could have been fixed by updating the user metadata thread
IDs as well, but these are not indexed and hence this would have
required a full scan of all stored thread IDs.  Ghost messages solve
this problem naturally by reusing the exact same thread ID and message
ID representation and indexing as regular messages.

Furthermore, thanks to this greater symmetry, ghost messages are also
algorithmically simpler.  We continue to support the old user metadata
format, so this patch can't delete any code, but when we do remove
support for the old format, several functions can simply be deleted.

[1] id:8738h7kv2q.fsf@qmul.ac.uk

lib: Internal support for querying and creating ghost messages

This updates the message abstraction to support ghost messages: it
adds a message flag that distinguishes regular messages from ghost
messages, and an internal function for initializing a newly created
(blank) message as a ghost message.

lib: Introduce macros for bit operations

These macros help clarify basic bit-twiddling code and are written to
be robust against C undefined behavior of shift operators.

lib: Update database schema doc for ghost messages

This describes the structure of ghost mail documents.  Ghost messages
are not yet implemented.

lib: Add a ghost messages database feature

This will be implemented over the next several patches.  The feature
is not yet "enabled" (this does not add it to
NOTMUCH_FEATURES_CURRENT).

Merge tag '0.18.2'

notmuch 0.18.2 release

debian: add changelog stanza for 0.18.2-1

version: bump to 0.18.2

No non-documentation changes

NEWS: give real entry for 0.18.2

Expand out what the actual test suite changes are, so people have a
better idea if the release is relevant to them.

Merge tag '0.18.2_rc1'

notmuch 0.18.2~rc1 release

Conflicts:
NEWS
debian/changelog

debian: build depend on dh-python

The build log asked me nicely, so I did.

debian: add changelog stanza for 0.18.2~rc-1

NEWS: add minimal news item for 0.18.2

The less said, the less typos to make.

version: bump to 0.18.2~rc1

test: kill '"filename": "signature.asc"' from json output

This starts to appear with emacs24.4, so we can't easily have it in
our expected output.

test/emacs: force *Messages* buffer to be writable

In emacs 24.4 the messages buffer starts being read-only, which kills
these tests.  This seems to be the point of the variable
inihibit-read-only, which has existed at least since emacs 21.

test: simplify T360-symbol-hiding, use nm instead of objdump

After yet another variation in objdump output caused this test to fail
(on a Debian port, no less), I decided whatever putative benefit we
get from looking at the object files instead of the library isn't
worth the maintenence headache.

This version uses nm -P. nm -P should be portable, and fixed format.
It purposely doesn't use the -D argument, since that is non-POSIX and
nm on GNU/Linux seems do the right thing without it.

It still won't work out of the box on e.g. Mac OS/X. I think the right
thing to do there is to move some more configuration information into
sh.config.

(cherry picked from commit c34d6bad0f9da300eac2181e2073aee130432932)

test: Port atomicity test to Python

Previously, this was implemented using a horrible GDB script (because
there is no such thing as a non-horrible GDB script).  This GDB script
often broke with newer versions of GDB for mysterious reasons.  Port
the test script to GDB's Python API, which makes the code much cleaner
and, hopefully, more stable.

(cherry picked from commit cbbda62258360f035894cff9dfd66c60b0cc707f)

Conflicts:
test/T380-atomicity.sh

README.rst: typo/wording fixes

It occurs that hardcoding the URL will not make sense in forks.
Mind you, the whole README won't make much sense in forks.

doc: add README.rst especially for github

Apparently README.rst overrides README, so this will show up instead
of our generic README on github.

If the user is already on github, then clicking a link for more
information is not a hardship.

VIM: Make starting in 'insert' mode for compose optional

This adds a variable to make starting in insert mode optional when
composing and replying to emails.  I found it unusual to be started in
insert mode so I thought I'd make it optional as others may find this as
well.

    Ian

VIM: Use notmuch CLI for config

This patch switches from reading .notmuch-config directly to using
the CLI the same way that emacs does it.  It actually uses less code
and is probably less error prone.

    Ian

test: check for gdb in insert tests

Commits a6cee01 and c48b12f otherwise break the build for people
without gdb.

test/insert: check that indexing errors are accepted with --keep

This is overkill for the current code path, but should provide some
robustness for future changes in error handling.

cli/insert: require succesful message indexing for success status

Add --keep option to keep any remaining stuff in index or file. We
could distinguish between failures to index and failures to apply tags
or maildir sync, but for simplicity just have one.

cli/insert: add fail path to add_file_to_database

Handle failures gracefully in add_file_to_database, renamed simply
add_file while at it. Add keep option to not remove the message from
database if tagging or tag syncing to maildir flags fails. Expand the
function documentation to cover the changes.

test/insert: add known broken tests for indexing failures

These tests are written with the assumption that we want all indexing
failures to be considered as failures by notmuch insert.

lib: Handle empty date value

In the interest of robustness, avoid undefined behavior of
sortable_unserialise if the date value is missing.  This shouldn't
happen now, but ghost messages will have blank date values.

lib: Refactor _notmuch_database_link_message

This moves the code to retrieve and clear the metadata thread ID out
of _notmuch_database_link_message into its own function.  This will
simplify future changes.

lib: Move message ID compression to _notmuch_message_create_for_message_id

Previously, this was performed by notmuch_database_add_message.  This
happens to be the only caller currently (which is why this was safe),
but we're about to introduce more callers, and it makes more sense to
put responsibility for ID compression in the lower-level function
rather than requiring each caller to handle it.

NEWS: mention the change in default build flags

It blows things up by a factor of six or so, so it's worth giving
people a heads up. It won't effect e.g. Debian, that already builds
with -g and then strips.

NEWS: Document "nmbug: Translate to Python"

For more details, see the commit message for 7f2cb3be (nmbug:
Translate to Python, 2014-10-03).  I realized while writing this that
the 7f2cb3be commit message has:

  * 'nmbug log' now execs 'git log', as there's no need to keep the
    Python process around once we've launched Git there.

But we dropped that exec in favor of the subprocess approach between
v3 and v4, I just forgot to update the commit message [1].

[1]: id:e630b6763e9d0771718afee41ea15b29bb4a1de8.1409935538.git.wking@tremily.us
     http://article.gmane.org/gmane.mail.notmuch.general/19007

hex-escape: remove unused variable default_buf_size

Found by clang:

CC  -O2 util/hex-escape.o
util/hex-escape.c:28:21: warning: unused variable 'default_buf_size'
      [-Wunused-const-variable]
static const size_t default_buf_size = 1024;
                    ^
1 warning generated.

test: Port atomicity test to Python

Previously, this was implemented using a horrible GDB script (because
there is no such thing as a non-horrible GDB script).  This GDB script
often broke with newer versions of GDB for mysterious reasons.  Port
the test script to GDB's Python API, which makes the code much cleaner
and, hopefully, more stable.

configure: add debug flags by default.

This makes development (in particular the test suite) easier. Those
concerned about the extra diskspace can override the default or use
strip.

test: check for debug symbols in notmuch

In the future, tests may rely on debug symbols being present in
notmuch, so we plan to switch the default flags.

The main purpose of this test is to help explain the perhaps
mysterious failures of other tests which rely on symbols being
present.

nmbug: Translate to Python

This allows us to capture stdout and stderr separately, and do other
explicit subprocess manipulation without resorting to external
packages.  It should be compatible with Python 2.7 and later
(including the 3.x series).

Most of the user-facing interface is the same, but there are a few
changes, where reproducing the original interface was too difficult or
I saw a change to make the underlying Git UI accessible:

* 'nmbug help' has been split between the general 'nmbug --help' and
  the command-specific 'nmbug COMMAND --help'.

* Commands are no longer split into "most common", "other useful", and
  "less common" sets.  If we need something like this, I'd prefer
  workflow examples highlighting common commands in the module
  docstring (available with 'nmbug --help').

* 'nmbug commit' now only uses a single argument for the optional
  commit-message text.  I wanted to expose more of the underlying 'git
  commit' UI, since I personally like to write my commit messages in
  an editor with the notes added by 'git commit -v' to jog my memory.
  Unfortunately, we're using 'git commit-tree' instead of 'git
  commit', and commit-tree is too low-level for editor-launching.  I'd
  be interested in rewriting commit() to use 'git commit', but that
  seemed like it was outside the scope of this rewrite.  So I'm not
  supporting all of Git's commit syntax in this patch, but I can at
  least match 'git commit -m MESSAGE' in requiring command-line commit
  messages to be a single argument.

* The default repository for 'nmbug push' and 'nmbug fetch' is now the
  current branch's upstream (branch.<name>.remote) instead of
  'origin'.  When we have to, we extract this remote by hand, but
  where possible we just call the Git command without a repository
  argument, and leave it to Git to figure out the default.

* 'nmbug push' accepts multiple refspecs if you want to explicitly
  specify what to push.  Otherwise, the refspec(s) pushed depend on
  push.default.  The Perl version hardcoded 'master' as the pushed
  refspec.

* 'nmbug pull' defaults to the current branch's upstream
  (branch.<name>.remote and branch.<name>.merge) instead of hardcoding
  'origin' and 'master'.  It also supports multiple refspecs if for
  some crazy reason you need an octopus merge (but mostly to avoid
  breaking consistency with 'git pull').

* 'nmbug log' now execs 'git log', as there's no need to keep the
  Python process around once we've launched Git there.

* 'nmbug status' now catches stderr, and doesn't print errors like:

    No upstream configured for branch 'master'

  The Perl implementation had just learned to avoid crashing on that
  case, but wasn't yet catching the dying subprocess's stderr.

* 'nmbug archive' now accepts positional arguments for the tree-ish
  and additional 'git archive' options.  For example, you can run:

    $ nmbug archive HEAD -- --format tar.gz

  I wish I could have preserved the argument order from 'git archive'
  (with the tree-ish at the end), but I'm not sure how to make
  argparse accept arbitrary possitional arguments (some of which take
  arguments).  Flipping the order to put the tree-ish first seemed
  easiest.

* 'nmbug merge' and 'pull' no longer checkout HEAD before running
  their command, because blindly clobbering the index seems overly
  risky.

* In order to avoid creating a dirty index, 'nmbug commit' now uses
  the default index (instead of nmbug.index) for composing the commit.
  That way the index matches the committed tree.  To avoid leaving a
  broken index after a failed commit, I've wrapped the whole thing in
  a try/except block that resets the index to match the pre-commit
  treeish on errors.  That means that 'nmbug commit' will ignore
  anything you've cached in the index via direct Git calls, and you'll
  either end up with an index matching your notmuch tags and the new
  HEAD (after a successful commit) or an index matching the original
  HEAD (after a failed commit).

doc: build notmuch-emacs info/html docs, link from index

Although this manual is far from complete, it may be helpful for
someone. In particular building it as part of the standard build
process makes it easier to find problems when editing the
notmuch-emacs-manual.

doc: Emacs manual improvements and expansions

Fix several typos, improve general wording and flow, and add some
information on notmuch-jump.

NEWS: News for notmuch-jump

lib: Simplify close and codify aborting atomic section

In Xapian, closing a database implicitly aborts any outstanding
transaction and commits changes.  For historical reasons,
notmuch_database_close had grown to almost, but not quite duplicate
this behavior.  Before closing the database, it would explicitly (and
unnecessarily) commit it.  However, if there was an outstanding
transaction (ie atomic section), commit would throw a Xapian
exception, which notmuch_database_close would unnecessarily print to
stderr, even though notmuch_database_close would ultimately abort the
transaction anyway when it called close.

This patch simplifies notmuch_database_close to explicitly abort any
outstanding transaction and then just call Database::close.  This
works for both read-only and read/write databases, takes care of
committing changes, unifies the exception handling path, and codifies
aborting outstanding transactions.  This is currently the only way to
abort an atomic section (and may remain so, since it would be
difficult to roll back things we may have cached from rolled-back
modifications).

cli/insert: rehash file writing functions

Make the function calls make more sense as independent building blocks
of the big picture, with clear inputs and outputs. Split up
write_message into two. Improve function documentation. Cleanup and
clarify the error paths.

cli/insert: abstract temporary filename generation

This will clean up the usage. There's the slight functional change of
potentially ending up doing extra gethostname and getpid calls, but
this is neglible.

cli/insert: use a single recursive mkdir function

Combine make_directory() and make_directory_and_parents() into a
single recursive mkdir_recursive() function. Clarify the code and
improve error handling. Improve error messages. Switch to using the
new function in maildir_create_folder(). Constify talloc context.

cli/insert: clean up sync_dir

Clarify the code slightly, improve error messages. Apart from the
error message changes, no functional changes.

cli/insert: rename file copy function

The copying has nothing to do with stdin, so call it copy_fd
instead. While at it, improve documentation and reverse the
parameters, as destination is traditionally the first parameter.

cli/insert: move add_file_to_database to a better place

Move add_file_to_database around to keep the filesystem related
functions grouped together, improving readability. No functional
changes.

cli/insert: rename check_folder_name to is_valid_folder_name

An "is something" predicate conveys the meaning better. While at it,
improve the function documentation and error message. Besides the
error message change, no functional changes.

lib: actually return failures from notmuch_message_tags_to_maildir_flags

The function takes great care to preserve the first error status it
encounters, yet fails to return that status to the caller. Fix it.