[PATCH] doc: clean up manpages
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. --- doc/man1/notmuch-address.rst | 12 ++-- doc/man1/notmuch-dump.rst | 2 +- doc/man1/notmuch-reply.rst| 2 +- doc/man1/notmuch-search.rst | 26 +- doc/man1/notmuch-show.rst | 14 +++--- doc/man7/notmuch-search-terms.rst | 4 ++-- 6 files changed, 30 insertions(+), 30 deletions(-) diff --git a/doc/man1/notmuch-address.rst b/doc/man1/notmuch-address.rst index c00d7d74..12d86e89 100644 --- a/doc/man1/notmuch-address.rst +++ b/doc/man1/notmuch-address.rst @@ -32,8 +32,8 @@ Supported options for **address** include ``--output=(sender|recipients|count|address)`` Controls which information appears in the output. This option can be given multiple times to combine different outputs. When -neither --output=sender nor --output=recipients is -given, --output=sender is implied. +neither ``--output=sender`` nor ``--output=recipients`` is +given, ``--output=sender`` is implied. **sender** Output all addresses from the *From* header. @@ -63,19 +63,19 @@ Supported options for **address** include **no** Output all occurrences of addresses in the matching -messages. This is not applicable with --output=count. +messages. This is not applicable with ``--output=count``. **mailbox** Deduplicate addresses based on the full, case sensitive name and email address, or mailbox. This is effectively the same as -piping the --deduplicate=no output to **sort | uniq**, except +piping the ``--deduplicate=no`` output to **sort | uniq**, except for the order of results. This is the default. **address** Deduplicate addresses based on the case insensitive address part of the mailbox. Of all the variants (with different name or case), print the one occurring most frequently among the -matching messages. If --output=count is specified, include all +matching messages. If ``--output=count`` is specified, include all variants in the count. ``--sort=``\ (**newest-first**\ \|\ **oldest-first**) @@ -86,7 +86,7 @@ Supported options for **address** include By default, results will be displayed in reverse chronological order, (that is, the newest results will be displayed first). -However, if either --output=count or --deduplicate=address is +However, if either ``--output=count`` or ``--deduplicate=address`` is specified, this option is ignored and the order of the results is unspecified. diff --git a/doc/man1/notmuch-dump.rst b/doc/man1/notmuch-dump.rst index f8ec4868..ec6335b2 100644 --- a/doc/man1/notmuch-dump.rst +++ b/doc/man1/notmuch-dump.rst @@ -21,7 +21,7 @@ incremental backup than the native database files.) See **notmuch-search-terms(7)** for details of the supported syntax for . With no search terms, a dump of all messages in -the database will be generated. A "--" argument instructs notmuch that +the database will be generated. A ``--`` argument instructs notmuch that the remaining arguments are search terms. Supported options for **dump** include diff --git a/doc/man1/notmuch-reply.rst b/doc/man1/notmuch-reply.rst index c893ba04..5c64c4a6 100644 --- a/doc/man1/notmuch-reply.rst +++ b/doc/man1/notmuch-reply.rst @@ -75,7 +75,7 @@ Supported options for **reply** include If ``true``, decrypt any MIME encrypted parts found in the selected content (i.e., "multipart/encrypted" parts). Status of the decryption will be reported (currently only supported -with --format=json and --format=sexp), and on successful +with ``--format=json`` and ``--format=sexp``), and on successful decryption the multipart/encrypted part will be replaced by the decrypted content. diff --git a/doc/man1/notmuch-search.rst b/doc/man1/notmuch-search.rst index e42da2ae..654c5f2c 100644 --- a/doc/man1/notmuch-search.rst +++ b/doc/man1/notmuch-search.rst @@ -47,25 +47,25 @@ Supported options for **search** include **threads** Output the thread IDs of all threads with any message matching -the search terms, either one per line (--format=text), -separated by null characters (--format=text0), as a JSON array -(--format=json), or an S-Expression list (--format=sexp). +the search terms, either one per line (``--format=text``), +separa
Re: [PATCH] emacs: new crypto customization variable to control stashing of encryption session keys
On Tue, Jun 19 2018, Daniel Kahn Gillmor wrote:
> This is looking good to me, thanks!
>
> two more bits of nit-pickery below:
>
> On Tue 2018-06-19 08:20:12 -0700, Jameson Graef Rollins wrote:
>> +(defcustom notmuch-show-stash-session-keys nil
>> + "Should session keys be stashed when decrypting messages for display?
>> +
>> +If this variable is non-nil session keys recovered while
>> +decrypting messages for display will be stored in the database.
>> +See description of --decrypt option in notmuch-show(1) for more
>> +information.
>
> do we want to include a warning here about the security of the index?
> setting this value to true not only stashes the session keys, but it
> also indexes the cleartext. at the moment we're not directing people to
> the same kind of warnings ("Be aware that the index… DO NOT USE …
> without considering the security of your index.") that are present
> already in notmuch-reindex(1) and notmuch-new(1) and notmuch-insert(1).
> Perhaps notmuch-show(1) needs the same boilerplate warning, and we could
> replicate some short version of it here too?
I was wondering if it would make sense to have a separate man page for
describing all the intricacies of notmuch's crypto functionality,
i.e. notmuch-crypto(7). There's going to be a lot of
redundancy/boilerplate in all the different man pages, and it seems like
it would be useful to put it all in one place and just reference it from
all the others.
This could also be a good place to describe how protected headers are
handled, and autocrypt once we finally get around to implementing it.
>> +NOTE: Stashing encryption session keys requires opening the
>> +notmuch database in read/write mode, which is not normally done
>
> i'd say "not otherwise done" instead of "not normally done", since we
> don't want to claim that people who use this feature aren't "normal" :)
But the claim wouldn't not be true!
I'll push another (five copies of a new) version.
jamie.
signature.asc
Description: PGP signature
___
notmuch mailing list
notmuch@notmuchmail.org
https://notmuchmail.org/mailman/listinfo/notmuch
Re: [PATCH] emacs: new crypto customization variable to control stashing of encryption session keys
This is looking good to me, thanks!
two more bits of nit-pickery below:
On Tue 2018-06-19 08:20:12 -0700, Jameson Graef Rollins wrote:
> +(defcustom notmuch-show-stash-session-keys nil
> + "Should session keys be stashed when decrypting messages for display?
> +
> +If this variable is non-nil session keys recovered while
> +decrypting messages for display will be stored in the database.
> +See description of --decrypt option in notmuch-show(1) for more
> +information.
do we want to include a warning here about the security of the index?
setting this value to true not only stashes the session keys, but it
also indexes the cleartext. at the moment we're not directing people to
the same kind of warnings ("Be aware that the index… DO NOT USE …
without considering the security of your index.") that are present
already in notmuch-reindex(1) and notmuch-new(1) and notmuch-insert(1).
Perhaps notmuch-show(1) needs the same boilerplate warning, and we could
replicate some short version of it here too?
> +NOTE: Stashing encryption session keys requires opening the
> +notmuch database in read/write mode, which is not normally done
i'd say "not otherwise done" instead of "not normally done", since we
don't want to claim that people who use this feature aren't "normal" :)
--dkg
signature.asc
Description: PGP signature
___
notmuch mailing list
notmuch@notmuchmail.org
https://notmuchmail.org/mailman/listinfo/notmuch
Re: [PATCH] emacs: new crypto customization variable to control stashing of encryption session keys
On Tue, Jun 19 2018, Jameson Graef Rollins wrote: > Introduce notmuch-show-store-session-keys customization variable to > control stashing of session keys. If non-nil any session keys > recovered during decryption will be stored in the database. > > This is just a switch to have --decrypt= use "stash" instead of > "true". > --- > Gah forgot to update the commit message. Sorry. Sorry, this is the one to use, since I messed up the commit message on the first. So sorry for all the screw ups. jamie. ___ notmuch mailing list notmuch@notmuchmail.org https://notmuchmail.org/mailman/listinfo/notmuch
[PATCH] emacs: new crypto customization variable to control stashing of encryption session keys
Introduce notmuch-show-store-session-keys customization variable to
control stashing of session keys. If non-nil any session keys
recovered during decryption will be stored in the database.
This is just a switch to have --decrypt= use "stash" instead of
"true".
---
Gah forgot to update the commit message. Sorry.
emacs/notmuch-crypto.el | 15 +++
emacs/notmuch-query.el | 4 +++-
2 files changed, 18 insertions(+), 1 deletion(-)
diff --git a/emacs/notmuch-crypto.el b/emacs/notmuch-crypto.el
index fc2b5301..26ce19b4 100644
--- a/emacs/notmuch-crypto.el
+++ b/emacs/notmuch-crypto.el
@@ -43,6 +43,21 @@ mode."
:package-version '(notmuch . "0.25")
:group 'notmuch-crypto)
+(defcustom notmuch-show-stash-session-keys nil
+ "Should session keys be stashed when decrypting messages for display?
+
+If this variable is non-nil session keys recovered while
+decrypting messages for display will be stored in the database.
+See description of --decrypt option in notmuch-show(1) for more
+information.
+
+NOTE: Stashing encryption session keys requires opening the
+notmuch database in read/write mode, which is not normally done
+when retrieving messages for display."
+ :type 'boolean
+ :package-version '(notmuch . "0.28")
+ :group 'notmuch-crypto)
+
(defface notmuch-crypto-part-header
'class color)
(background dark))
diff --git a/emacs/notmuch-query.el b/emacs/notmuch-query.el
index 563e4acf..e53c9489 100644
--- a/emacs/notmuch-query.el
+++ b/emacs/notmuch-query.el
@@ -32,7 +32,9 @@ is a possibly empty forest of replies.
"
(let ((args '("show" "--format=sexp" "--format-version=4")))
(if notmuch-show-process-crypto
- (setq args (append args '("--decrypt=true"
+(if notmuch-show-stash-session-keys
+(setq args (append args '("--decrypt=stash")))
+ (setq args (append args '("--decrypt=true")
(setq args (append args search-terms))
(apply #'notmuch-call-notmuch-sexp args)))
--
2.17.1
___
notmuch mailing list
notmuch@notmuchmail.org
https://notmuchmail.org/mailman/listinfo/notmuch
[PATCH] emacs: new crypto customization variable to control stashing of encryption session keys
Introduce notmuch-crypto-store-session-keys customization variable to
control stashing of session keys. If non-nil any session keys
recovered during decryption will be stored in the database.
This is just a switch to have --decrypt= use "stash" instead of
"true".
---
emacs/notmuch-crypto.el | 15 +++
emacs/notmuch-query.el | 4 +++-
2 files changed, 18 insertions(+), 1 deletion(-)
diff --git a/emacs/notmuch-crypto.el b/emacs/notmuch-crypto.el
index fc2b5301..26ce19b4 100644
--- a/emacs/notmuch-crypto.el
+++ b/emacs/notmuch-crypto.el
@@ -43,6 +43,21 @@ mode."
:package-version '(notmuch . "0.25")
:group 'notmuch-crypto)
+(defcustom notmuch-show-stash-session-keys nil
+ "Should session keys be stashed when decrypting messages for display?
+
+If this variable is non-nil session keys recovered while
+decrypting messages for display will be stored in the database.
+See description of --decrypt option in notmuch-show(1) for more
+information.
+
+NOTE: Stashing encryption session keys requires opening the
+notmuch database in read/write mode, which is not normally done
+when retrieving messages for display."
+ :type 'boolean
+ :package-version '(notmuch . "0.28")
+ :group 'notmuch-crypto)
+
(defface notmuch-crypto-part-header
'class color)
(background dark))
diff --git a/emacs/notmuch-query.el b/emacs/notmuch-query.el
index 563e4acf..e53c9489 100644
--- a/emacs/notmuch-query.el
+++ b/emacs/notmuch-query.el
@@ -32,7 +32,9 @@ is a possibly empty forest of replies.
"
(let ((args '("show" "--format=sexp" "--format-version=4")))
(if notmuch-show-process-crypto
- (setq args (append args '("--decrypt=true"
+(if notmuch-show-stash-session-keys
+(setq args (append args '("--decrypt=stash")))
+ (setq args (append args '("--decrypt=true")
(setq args (append args search-terms))
(apply #'notmuch-call-notmuch-sexp args)))
--
2.17.1
___
notmuch mailing list
notmuch@notmuchmail.org
https://notmuchmail.org/mailman/listinfo/notmuch
Re: [PATCH] emacs: new crypto customization variable to control stashing of encryption session keys
On Tue, Jun 19 2018, David Bremner wrote: > I'm fine with whatever you and dkg decide for a name, but note that the > customization group is independent from the name; you just choose > whatever group you want in the defcustom. Oh, I didn't realize that. I thought they were linked. In that case I'll go with: notmuch-show-store-session-keys signature.asc Description: PGP signature ___ notmuch mailing list notmuch@notmuchmail.org https://notmuchmail.org/mailman/listinfo/notmuch
[gmailieer] Gmailieer v0.9 released
Hi, Gmailieer v0.9 has been released! https://github.com/gauteh/gmailieer Gmailieer provides fast email-fetching and two-way tag synchronization between notmuch and GMail. Changes: * Fix docs and help (timeout 0 means min (forver, system-timeout)). * All output is ASCII, ensures working on all outputs (read non-ttys / pipes). Regards, Gaute pgpUJFFfQSxGq.pgp Description: PGP signature ___ notmuch mailing list notmuch@notmuchmail.org https://notmuchmail.org/mailman/listinfo/notmuch
Re: [PATCH] emacs: new crypto customization variable to control stashing of encryption session keys
Jameson Graef Rollins writes: > On Mon, Jun 18 2018, Daniel Kahn Gillmor wrote: >> This looks like it would work, but calling it >> notmuch-crypto-store-session-keys is a bit confusing, because based on >> the name it looks like it would apply to many places (e.g. during >> message sending, should a session key be stored when the outbound >> message is fcc'ed?), but based on the implementation it only matters >> during "show". >> >> Should its name be notmuch-show-store-session-keys instead? > > I feel like it should be under the notmuch-crypto customization group, > not notmuch-show. notmuch-crypto-show-store-session-keys ? > I'm fine with whatever you and dkg decide for a name, but note that the customization group is independent from the name; you just choose whatever group you want in the defcustom. d ___ notmuch mailing list notmuch@notmuchmail.org https://notmuchmail.org/mailman/listinfo/notmuch
