notmuch/doc/man1/notmuch-insert.rst, branch master

doc: define and use semantic markup for configuration items

2022-05-21T01:40:32Z

This makes sure each configuration item is cross referenceable without extra markup, and also adds index entries.

doc: use hyperlinks for config options in notmuch-insert(1)

2022-02-20T13:33:56Z

The tradeoff is no bold/italic in the man pages to get actual hyperlinks in the html output.

doc: add configuration section to notmuch-insert(1)

2022-02-20T13:33:56Z

This is partially redudant given some existing cross references, but it is useful to have all of the config keys listed in one place, to help keep track of them if nothing else.

doc: mail store is given by database.mail_root

2022-01-03T12:07:13Z

The mail store directory is given by database.mail_root, which can be different from database.path. However, notmuch-insert documentation was still referencing the latter as the provider of the maildir directory instead of the former.

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

cli/insert: add --world-readable flag

2018-03-24T23:08:11Z

In some cases (e.g. when building a publicly-visible e-mail archive) it doesn't make any sense to restrict visibility of the message to the current user account. This adds a --world-readable boolean option for "notmuch insert", so that those who want to archive their mail publicly can feed their archiver with: notmuch insert --world-readable Other local delivery agents (postfix's local, and dovecot's lda) all default to delivery in mode 0600 rather than relying on the user's umask, so this fix doesn't change the default. Also, this does not override the user's umask. if the umask is already set tight, it will not become looser as the result of passing --world-readable. 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.

crypto: add --decrypt=nostash to avoid stashing session keys

2017-12-08T12:08:47Z

Here's the configuration choice for people who want a cleartext index, but don't want stashed session keys. Interestingly, this "nostash" decryption policy is actually the same policy that should be used by "notmuch show" and "notmuch reply", since they never modify the index or database when they are invoked with --decrypt. We take advantage of this parallel to tune the behavior of those programs so that we're not requesting session keys from GnuPG during "show" and "reply" that we would then otherwise just throw away.

crypto: actually stash session keys when decrypt=true

2017-12-08T12:08:47Z

If you're going to store the cleartext index of an encrypted message, in most situations you might just as well store the session key. Doing this storage has efficiency and recoverability advantages. Combined with a schedule of regular OpenPGP subkey rotation and destruction, this can also offer security benefits, like "deletable e-mail", which is the store-and-forward analog to "forward secrecy". But wait, i hear you saying, i have a special need to store cleartext indexes but it's really bad for me to store session keys! Maybe (let's imagine) i get lots of e-mails with incriminating photos attached, and i want to be able to search for them by the text in the e-mail, but i don't want someone with access to the index to be actually able to see the photos themselves. Fret not, the next patch in this series will support your wacky uncommon use case.