notmuch/doc/man1/notmuch.rst, branch 0.35

doc: document database search algorithm.

2021-08-21T14:54:44Z

Essentially a translation of the function _choose_database_path for human consumption. As a bonus, document environment variable NOTMUCH_DATABASE

replace references to freenode with references to libera

2021-07-06T20:20:03Z

I left the reference to freenode in the test suite data, since it is historical.

doc: use program and option directives to document options

2021-05-22T19:43:24Z

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.

doc: use envvar directive and role for environment variables

2021-05-22T19:41:20Z

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.

doc: cross-reference notmuch man pages with actual links

2021-05-22T19:38:56Z

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.

doc: use manpage role references to external man pages

2021-05-22T12:56:52Z

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.

CLI/config: default to storing all config in external files

2021-03-27T12:26:14Z

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

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: unify definition list usage across man pages

2017-12-31T13:06:11Z

Make all parameter descriptions etc. use reStructuredText definition lists with uniform style and indentation. Remove redundant indentation from around the lists. Remove blank lines between term lines and definition blocks. Use four spaces for indentation. This is almost completely whitespace and paragraph reflow changes.

doc: add notmuch-properties(7)

2017-10-21T22:52:55Z

We will want a user-facing place to record details about the use of notmuch properties shortly. This establishes a new manual page for that purpose.