notmuch/doc, branch debian/0.31.2-3

Rename version to version.txt

2020-10-30T19:14:24Z

Building Notmuch on macOS is known to cause problems because the Notmuch distribution archive contains two files named "version". These names clash with the header as defined in C++20. Therefore, the existing naming will likely become a problem on other platforms as well, once compilers adopt the new standard. Signed-off-by: Ralph Seichter Amended-by: db s/keyword/header/ in commit message.

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

2020-08-10T00:14:36Z

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

doc: add new python bindings to main documentation tree.

2020-07-15T11:37:11Z

A separate conf.py and doc directory (or will be needed if someone wants to build the bindings docs separately from notmuch.

doc: replace use of environment variables with a generated config

2020-07-15T11:32:15Z

It is getting unwieldy to pass configuration options on the sphinx-build command line, and I anticipate further use of conditionals. As far as I could tell, execing a string is the idiomatic way to emulate include in Python.

doc: make gzipped man pages reproducible

2020-07-11T16:57:17Z

gzip includes the name of the uncompressed file and its modification timestamp into the compressed archive. The latter makes it hard to reproduce the generated files bit for bit at a later time, so omit this information from the archive using the "--no-name" option. This is a reproducibility best practice, see https://wiki.debian.org/ReproducibleBuilds/TimestampsInGzipHeaders

doc: field processor support now always included, adjust manual pages

2020-06-06T10:54:34Z

The features that require field processor support, are now just documented w/o mentioning **Xapian Field Processors**' is needed for those. Replaced "compact" and "field_processor" with "retry_lock" in build_with config option, as it is currently the only one that is optionally excluded. The former 2 are now documented as features always included. Dropped one 'we' "passive" in notmuch-search-terms.rst. It was the only one, and inconsistent with rest of the documentation in that file. Dropped message about conditional open-ended ranges support, as those are now always supported.

bump date in documentation

2020-06-01T23:58:52Z

doc: fix for out-of-tree builds of notmuch-emacs docs

2020-06-01T12:07:50Z

The sphinx-doc include directive does not have the ability to include files from the build tree, so we replace the include with reading the files in conf.py. The non-trivial downside of this is that the emacs docstrings are now defined for every rst source file. They are namespaced with docstring::, so hopefully there will not be any surprises. One thing that is noticable is a small (absolute) time penalty in running sphinx-doc.

notmuch(1): clarify documentation about --option/value separators

2020-05-08T11:58:46Z

id:CA+Tk8fzRiqxWpd=r8=DRvEewNZXUZgD7MKyRLB1A=R-LxxGEZw@mail.gmail.com started a thread of discussion that showed that the cli's current idiosyncrasies around dealing with boolean options were not understandable. This attempts to improve the documentation at least (actual changes to the API might be better, but have not reached consensus). Note that no one in the discussion thread identified any other (non-boolean) command-line options that cannot use space as a separator. If such an option is identified (or introduced in the future), it should be added explicitly to this part of the manual. Signed-off-by: Daniel Kahn Gillmor

doc: Drop obsolete MSCGEN_PATH, PERL_PATH from doxygen configuration

2020-04-02T01:46:58Z

Since doxygen 1.8.16, MSCGEN_PATH and PERL_PATH are obsolete: MSCGEN_PATH: https://github.com/doxygen/doxygen/commit/873e0ccfbe43ef98d4858beb08eef37631ae3cf6 PERL_PATH: https://github.com/doxygen/doxygen/commit/6d1535c38fe6bdaa2a00fff0e7e43774a740a4ce I don't think that the notmuch builds ever depended on them in the first place, and including them in the default config yields the following two warnings: ``` doxygen ./doc/doxygen.cfg warning: Tag 'PERL_PATH' at line 267 of file './doc/doxygen.cfg' has become obsolete. To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u" warning: Tag 'MSCGEN_PATH' at line 272 of file './doc/doxygen.cfg' has become obsolete. To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u" ``` Remove them to avoid the warnings. Signed-off-by: Daniel Kahn Gillmor