In [1] Daniel observed that the gzipped man pages were only being
rebuild every second time when building with `make -j4'. This may be
caused by a race condition between sphinx-build rebuilding the roff
files and the recipe to gzip them. This commit sequentializes these
two steps by making the stamp file a prerequisite for (all of) the
gzip files.
[1]: id:87tveotn1g.fsf@fifthhorseman.net
Since release 0.32, libnotmuch provides searching for database and
configuration paths. This commit changes the python module notmuch2 to
use those facilities.
This fixes the bug reported in [1], along with a couple of the
deprecation warnings in the python bindings.
Database.default_path is deprecated, since it no longer faithfully
reflects what libnotmuch is doing, and it is also no longer used in
the bindings themselves.
This commit choose the default of config=CONFIG.EMPTY (equivalent to
passing "" to notmuch_database_open_with_config). This makes the
change upward compatible API-wise (at least as far as the test suite
verifies), but changing the default to CONFIG.SEARCH would probably be
more convenient for bindings users.
[1]: id:87h7d4wp6b.fsf@tethera.net
The <backtab> binding has always been there, but the docs were
apparently mistakenly changed to say <backspace> [1]
Revert to <backtab> in the documentation.
The commit also drops the C-<tab> binding, since it seems redundant
and it interferes with tab-bar-mode.
[1]: 703dec7754.
Previously the python-cffi bindings either failed to build, or built
for the wrong module by using the installed module.
The fix requires correction the module path, building the bindings
before docs, and helping python find the built libnotmuch.
Based on patch / discussion from Micheal Gruber [1]
[1]: id:cover.1634808719.git.git@grubix.eu
It is confusing to use two different names (sexp vs sexpr) when
compared with the command line option --query=sexp and (furthermore)
singular vs plural when compared with the man page title.
This document contains meaningful markup in the terms, which makeinfo
complains about. Replace the use of definition lists with regular
paragraphs containing quote blocks. This is accomplished by splitting
the "term" from the definition with a blank line.
Sphinx-doc already formats the terms appropriately for a given
backend (bold in html and man). `makeinfo` complains noisily about
formatting inside a @item if we add our own explicit formatting.
This change may change the formatting in the info output. On the other
hand, the existing use of quotes for bold is not that great anyway.
In some places blank lines were removed to preserve the logical
structure of a definition list.
Macros implement lazy evaluation and lexical scope. The former is
needed to make certain natural constructs work sensibly (e.g. (tag
,param)) but the latter is mainly future-proofing in case the DSL is
is extended to allow local bindings.
For technical background, see chapters 6 and 17 of [1] (or some other
intermediate programming languages textbook).
[1] http://cs.brown.edu/courses/cs173/2012/book/
This commit does not enable using saved s-expression queries, only
saving and retrieving them from the config file or the database. Use
in queries will be enabled in a following commit.
This provides functionality analogous to query: in the Xapian
QueryParser based parser. Perhaps counterintuitively, the saved
queries currently have to be in the original query syntax (i.e. not
s-expressions).
One subtle aspect is the replacement of _find_prefix with
_notmuch_database_prefix, which understands user headers. Otherwise
the code mainly consists of creating a fake prefix record (since the
user prefixes are not in the prefix table) and error handling.
This is necessary so that programs can take infix syntax queries from
a user and use the sexp query syntax to construct e.g. a refinement of
that query.
At least to the degree that the Xapian QueryParser based parser
also supports them. Support short alias 'rx' as it seems to make more
complex queries nicer to read.
The many tests potentially overkill, but they could catch typos in the
prefixes table. As a simplifying assumption, for now we assume a
single argument to the wildcard operator, as this matches the Xapian
semantics. The name 'starts-with' is chosen to emphasize the supported
case of wildcards in currrent (1.4.x) Xapian.
We use "boolean" to describe fields that should generate terms
literally without stemming or phrase splitting. This terminology
might not be ideal but it is already enshrined in
notmuch-search-terms(7).
Anything that is quoted or not purely word characters is considered a
phrase. Phrases are not stemmed, because the stems do not have
positional information in the database. It is less efficient to scan
the term twice, but it avoids a second pass to add prefixes, so maybe
it balances out. In any case, it seems unlikely query parsing is very
often a bottleneck.
All operations and (Xapian) fields will eventually have an entry in
the prefixes table. The flags field is just a placeholder for now, but
will eventually distinguish between various kinds of prefixes.
There is not much of a parser here yet, but it already does some
useful error reporting. Most functionality sketched in the
documentation is not implemented yet; detailed documentation will
follow with the implementation.
This new command for notmuch-tree-mode is analogous to
notmuch-search-filter-by-tag, bound to "t" in notmuch-search-mode; it
gets therefore the same "t" keybinding in notmuch-tree-mode (replacing
the current assignment to notmuch-search-by-tag).
New --sort CLI option documented in notmuch-show's man page, and
notmuch-search-toggle-order mentioned in doc/notmuch-emacs.rst and
devel/emacs-keybindings.org (in the latter, there's also some
whitespace changes in a table introduced by org-mode).
After some discussion [1], I decided it is better to make notmuch users
who rely on this behaviour customize mail-user-agent. This is
consistent with the behaviour of other emacs mail packages.
[1]: id:87k0nuhfrk.fsf@toryanderson.com
Example reference to a command-line option using the option role
reference. This creates a hyperlink in html, and the usual boldface
style in man page. This could be used throughout the man pages.
Use the program and option directives to document the subcommand
options. This unifies a lot of option documentation throughout.
This also makes it possible to reference options with :option:`--foo`
(within .. program::) or :option:`subcommand --foo` (globally). This
is left for later work.
See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-program
Note: There is a lot of indentation change, but intentionally there is
no reflow. Using 'git diff -w' or 'git show -w' to ignore white space
changes makes this a very easy change to review.
Make man1/notmuch.rst the single point of truth for describing notmuch
environment variables. Use the envvar directive for that, and
reference them with the envvar role.
Drive-by cleanup configuration file and hook directory search order
documentation.
Add internal hyperlink targets for man pages and cross-reference them
using the any role reference. There are a number of alternatives to
accomplish this, but this seems like the combination that retains the
man page section number and the same boldface style in the man pages.
As a bonus, we get sanity checking on the links; for example
notmuch-search-terms.rst had a reference to notmuch-properties(1)
i.e. the wrong section.
The obvious semantic follow-up change would be to only have meaningful
"see also" references instead of having them all everywhere.
Using manpage role references generates helpful links in html
documentation, while retaining the same boldface style in the man
pages.
The external man page site is configurable. The Debian manpage site
seems like a good fit for Notmuch.
Variable 'notmuch-saved-searches-sort-function' does not exist;
'notmuch-saved-search-sort-function' is the correct name.
Signed-off-by: Luis Henriques <henrix@camandro.org>
Sphinx 4.0 changed the default value of man_make_section_directory
from False to True. We create the section directories and move the
files manually, so fix the immediate man build failure by disabling
the feature.
The Sphinx documentation on this [1] is confusing, and has the change
backwards. Git history says the default changed from False to True.
[1] https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-man_make_section_directory
Variable 'notmuch-saved-searches-sort-function' does not exist;
'notmuch-saved-search-sort-function' is the correct name.
Signed-off-by: Luis Henriques <henrix@camandro.org>
Sphinx 4.0 changed the default value of man_make_section_directory
from False to True. We create the section directories and move the
files manually, so fix the immediate man build failure by disabling
the feature.
The Sphinx documentation on this [1] is confusing, and has the change
backwards. Git history says the default changed from False to True.
[1] https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-man_make_section_directory
Previously the fact that some configuration options were only stored
in the database (and thus editing the config file had no effect) was a
source of user confusion. This was fixed with the series ending at
d9af0af164.
On the other hand, the underlying partition of config options into
those stored by default in the database and those stored in the config
file remained. This is also confusing, since now some invocations of
"notmuch config set" modify the config file, and others silently
modify the database instead.
With this commit, it is up to the user to decide which configuration
to modify. A new "--database" option is provided for notmuch config to
enable modifying the configuration information in the database;
otherwise the default is to update an external config file.
Introduce a new configuration value for the mail root, and use it to
locate mail messages in preference to the database.path (which
previously implied the mail messages were also in this location.
Initially only a subset of the CLI is tested in a split
configuration. Further changes will be needed for the remainder of the
CLI to work in split configurations.
Remove STORED IN DATABASE discussion, describe search rules.
Currently profiles seem a bit pointless. They will make more sense
when they apply to databases as well.
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
Building Notmuch on macOS is known to cause problems because the Notmuch
distribution archive contains two files named "version". These names
clash with the <version> 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 <github@seichter.de>
Amended-by: db s/keyword/header/ in commit message.
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).
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.
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
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.
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.
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 <dkg@fifthhorseman.net>
Since doxygen 1.8.16, MSCGEN_PATH and PERL_PATH are obsolete:
MSCGEN_PATH:
873e0ccfbe
PERL_PATH:
6d1535c38f
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 <dkg@fifthhorseman.net>
crypto.gpg_path was only used when we built against gmime versions
before 3.0. Since we now depend on gmime 3.0.3 or later, it is
meaningless.
The removal of the field from the _notmuch_config struct would be an
ABI change if that struct were externally exposed, but it is not, so
it's safe to unilaterally remove it.
Signed-off-by: Daniel Kahn Gillmor <dkg@fifthhorseman.net>
The escaping in the description of the output of "notmuch-config list"
appears to have been inherited from some previous attempts at
documentation. It leaked out in the actual generated manpage
documentation, where it looks like this:
list Every configuration item is printed to stdout, each on a
separate line of the form:
*section*.\ *item*\ =\ *value*
This simplification cleans up the overescaping.
Signed-off-by: Daniel Kahn Gillmor <dkg@fifthhorseman.net>
When encountering a message that has been mangled in the "mixed up"
way by an intermediate MTA, notmuch should instead repair it and index
the repaired form.
When it does this, it also associates the index.repaired=mixedup
property with the message. If a problem is found with this repair
process, or an improved repair process is proposed later, this should
make it easy for people to reindex the relevant message. The property
will also hopefully make it easier to diagnose this particular problem
in the future.
Signed-off-by: Daniel Kahn Gillmor <dkg@fifthhorseman.net>
When we notice a legacy-display part during indexing, it makes more
sense to avoid indexing it as part of the message body.
Given that the protected subject will already be indexed, there is no
need to index this part at all, so we skip over it.
If this happens during indexing, we set a property on the message:
index.repaired=skip-protected-headers-legacy-display
Signed-off-by: Daniel Kahn Gillmor <dkg@fifthhorseman.net>
This adds no functionality directly, but is a useful starting point
for adding new repair functionality.
Signed-off-by: Daniel Kahn Gillmor <dkg@fifthhorseman.net>
The extra flexibility of having both HAVE_EMACS (for yes, there is an
emacs we can use) and WITH_EMACS (the user wants emacs support) lead
to confusion and bugs. We now just force WITH_EMACS to 0 if no
suitable emacs is detected.
In 40b025 we stopped building the notmuch-emacs documentation if
HAVE_EMACS=0 (i.e. no emacs was detected by configure). Unfortunately
we continued to try to install the (non-existent) documentation, which
causes build/install failures.
As a bonus, we also avoid installing the documentation if the user
configures --without-emacs.
Thanks to Ralph Seichter for reporting the problem, and testing
previous versions of this fix.
Since the docstrings are not built in the case of --without-emacs,
even if emacs is detected, don't let sphinx build the emacs docs. This
avoids a large number of error messages due to missing includes. It's
actually a bit surprising sphinx doesn't generate an error for the
missing include files.
It seems our previous attempt with order-only targets was not
sufficient to avoid problems with sphinx-builds doctree cache [0].
Looking around at other people's approaches [1], using separate
doctrees was suggested. I guess there might be a slight loss of
efficiency, but it seems more robust.
[0]: build failures were first noticed in Debian experimental, but I was able to duplicate it in
my usual build environment about 1 in 8 builds.
[1]: in particular
9e3fc1657d
The new `body:` field (in Xapian terms) or prefix (in slightly
sloppier notmuch) terms allows matching terms that occur only in the
body.
Unprefixed query terms should continue to match anywhere (header or
body) in the message.
This follows a suggestion of Olly Betts to use the facility (since
Xapian 1.0.4) to add the same field with multiple prefixes. The double
indexing of previous versions is thus replaced with a query time
expension of unprefixed query terms to the various prefixed
equivalent.
Reindexing will be needed for 'body:' searches to work correctly;
otherwise they will also match messages where the term occur in
headers (demonstrated by the new tests in T530-upgrade.sh)
Without this change, we see this during the build:
sphinx-build -b html -d doc/_build/doctrees -q ./doc doc/_build/html
…/doc/notmuch-emacs.rst:67: WARNING: Unexpected indentation.
…/doc/notmuch-emacs.rst:165: WARNING: Unexpected indentation.
…/doc/notmuch-emacs.rst:306: WARNING: Unexpected indentation.
This source change doesn't seem to have any effect on the generated
HTML, at least.
Signed-off-by: Daniel Kahn Gillmor <dkg@fifthhorseman.net>
This should silence some warnings about the jobserver, but also make
it easier to build the docs where GNU make is called something other
than make.
Based on a patch from aidecoe.
In certain conditions the parallel calls to sphinx-build could
collide, yielding a crash like
Exception occurred:
File "/usr/lib/python3/dist-packages/sphinx/environment.py", line 1261, in get_doctree
doctree = pickle.load(f)
EOFError: Ran out of input
Many of the manpages didn't treat literal text as literal text. I've
tried to normalize some of the restructured text to make it a bit more
regular.
several of the synopsis lines are still untouched by this cleanup, but
i'm not sure what the right way to represent those is in .rst,
actually.
In particular find that if i rebuild the manpages, sometimes i end up
with some of the synopsis lines showing – (U+2013 EN DASH) where they
should have -- (2 × U+002D HYPHEN-MINUS) in the generated nroff
output, though i have not tracked down the source of this error yet.
This is mainly to improve discoverability. It seems that doing
variable cross-references is not easy without using some sphinx
extension/customization.
