bug#34726: epa-insert-keys

bug#34726: epa-insert-keys

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

In the buffer made by epa-insert-keys, the first character
in each line gives some status information about the key.
I don't know what the characters mean, most of them.

How about putting that info into the doc string of epa-insert-keys and
maybe also in the first line of that buffer?

-- 
Dr Richard Stallman
President, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

bug#34726: epa-insert-keys

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Sun, 03 Mar 2019 22:27:25 -0500
> 
> In the buffer made by epa-insert-keys, the first character
> in each line gives some status information about the key.
> I don't know what the characters mean, most of them.
> 
> How about putting that info into the doc string of epa-insert-keys and
> maybe also in the first line of that buffer?

AFAIU, that text is generated by GnuPG the program, so the
interpretation of those one-letter flags should be in the GPG manual?

bug#34726: epa-insert-keys

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > AFAIU, that text is generated by GnuPG the program, so the
  > interpretation of those one-letter flags should be in the GPG manual?

That is not conveniently helpful for Emacs users.  I think the
buffer, or the doc string, should explain these lettsrs.

There could also be a reference to the right place in the GPG manual.

Could someone please take care of this?

-- 
Dr Richard Stallman
President, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

bug#34726: epa-insert-keys

[Robert Pluim]

>>>>> On Tue, 05 Mar 2019 21:15:05 -0500, Richard Stallman <rms@gnu.org> said:
    rms> That is not conveniently helpful for Emacs users.  I think
    rms> the buffer, or the doc string, should explain these lettsrs.

    rms> There could also be a reference to the right place in the GPG
    rms> manual.

The relevant section of the GPG manual says:

    TRUST VALUES
           Trust  values  are used to indicate ownertrust and validity of keys and
           user IDs.  They are displayed with letters or strings:

           -      unknown No ownertrust assigned / not yet calculated.

           e      expired

                  Trust calculation has failed; probably due to an expired key.

           q      undefined, undef Not enough information for calculation.

           n      never Never trust this key.

           m      marginal Marginally trusted.

           f      full Fully trusted.

           u      ultimate Ultimately trusted.

           r      revoked For validity only: the key  or  the  user  ID  has  been
                  revoked.

           ?      err The program encountered an unknown trust value.


which is a bit too much for epa-insert-keys, I think. How about:

diff --git a/lisp/epa.el b/lisp/epa.el
index e442c12a7d..7cb15b5165 100644
--- a/lisp/epa.el
+++ b/lisp/epa.el
@@ -421,7 +421,9 @@ epa--list-keys
 
 ;;;###autoload
 (defun epa-list-keys (&optional name)
-  "List all keys matched with NAME from the public keyring."
+  "List all keys matched with NAME from the public keyring.
+
+See `epa-insert-keys' for a description of the format."
   (interactive
    (if current-prefix-arg
        (let ((name (read-string "Pattern: "
@@ -433,7 +435,9 @@ epa-list-keys
 
 ;;;###autoload
 (defun epa-list-secret-keys (&optional name)
-  "List all keys matched with NAME from the private keyring."
+  "List all keys matched with NAME from the private keyring.
+
+See `epa-insert-keys' for a description of the format."
   (interactive
    (if current-prefix-arg
        (let ((name (read-string "Pattern: "
@@ -1308,7 +1312,12 @@ epa-export-keys
 
 ;;;###autoload
 (defun epa-insert-keys (keys)
-  "Insert selected KEYS after the point."
+  "Insert selected KEYS after point.
+
+This will display a list of keys with their validity status,
+keyid, and associated name.  See 'TRUST VALUES' in the gpg
+documentation for the meaning of the letters describing the
+validity status."
   (interactive
    (list (epa-select-keys (epg-make-context epa-protocol)
 			  "Select keys to export.

bug#34726: epa-insert-keys

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

     The relevant section of the GPG manual says:

    TRUST VALUES
           Trust  values  are used to indicate ownertrust and validity of keys and
           user IDs.  They are displayed with letters or strings:

           -      unknown No ownertrust assigned / not yet calculated.

           e      expired

                  Trust calculation has failed; probably due to an expired key.

           q      undefined, undef Not enough information for calculation.

           n      never Never trust this key.

           m      marginal Marginally trusted.

           f      full Fully trusted.

           u      ultimate Ultimately trusted.

           r      revoked For validity only: the key  or  the  user  ID  has  been
                  revoked.

           ?      err The program encountered an unknown trust value.

Thanks for finding that.  I would not have had an easy time finding it
myself.

  > +This will display a list of keys with their validity status,
  > +keyid, and associated name.  See 'TRUST VALUES' in the gpg
  > +documentation 

That is too vague to be helpful.  It tells the reader to search for
some other publication, and doesn't even say precisely what
publication or what its name is -- let alone where to look.

I don't think I could have got anywhere from it.


I think we should include a cleaned-up and clarified version of this
table in those two commands' doc strings.

But we need to fill in some gaps.  From that text, it is not clear
what q means.  Also, it is oriented towards answering the question
"what does the trust calculation do with this key" rather than "what
is the status of this key".

GNU documentation should try to be _helpful_ and present material in
terms of what the user wants to know.

Attempting to convert the list above into practical meanings for
a user, here's my draft for an improved table.

           e      key has expired
           r      Key has been revoked.

           How much trust to put in signatures of other keys by this one:
           n      none
           m      marginal trust
           f      full trust (for instance, you signed this key)
           u      ultimate trust

[I don't entirely understand those.  I do not understand GPG's trust
facilities, I don't want to learn to understand them; what I really
want to know is whether I signed that key.  How can I tell that?]

           ?      inconsistency in key ring trust data
	   q      some other strange case

[What does that really mean?  How does q differ from hyphen?]

Can anyone clear up the unclear points?



-- 
Dr Richard Stallman
President, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

bug#34726: epa-insert-keys

[Robert Pluim]

>>>>> On Wed, 06 Mar 2019 22:38:02 -0500, Richard Stallman <rms@gnu.org> said:
    rms> Thanks for finding that.  I would not have had an easy time
    rms> finding it myself.

I had some trouble finding it myself.

    >> +This will display a list of keys with their validity status,
    >> +keyid, and associated name.  See 'TRUST VALUES' in the gpg
    >> +documentation

    rms> That is too vague to be helpful.  It tells the reader to
    rms> search for some other publication, and doesn't even say
    rms> precisely what publication or what its name is -- let alone
    rms> where to look.

The gpg documentation can be a man page or an info manual, plus there
are html and pdf version of the same documentation available from the
gpg website. We could just point people at

<https://www.gnupg.org/documentation/manuals/gnupg/Trust-Values.html>

    rms> I think we should include a cleaned-up and clarified version
    rms> of this table in those two commands' doc strings.

Thatʼs not a path Iʼd want to go down. The gpg documentation is long
and complex, because itʼs a complex program. Attempting to summarise
it in a few docstrings will result in incomplete or possibly incorrect
information, Iʼd rather people read the original.

Robert

bug#34726: epa-insert-keys

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Thatʼs not a path Iʼd want to go down. The gpg documentation is long
  > and complex, because itʼs a complex program. Attempting to summarise
  > it in a few docstrings will result in incomplete or possibly incorrect
  > information, Iʼd rather people read the original.

What in the "original" should I read?  I looked at the GPG Info file
which that text came from, as an Info file, but I see no further info
there to understand what those letters actually mean.

-- 
Dr Richard Stallman
President, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

bug#34726: epa-insert-keys

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Thu, 07 Mar 2019 23:14:54 -0500
> Cc: 34726@debbugs.gnu.org
> 
> What in the "original" should I read?  I looked at the GPG Info file
> which that text came from, as an Info file, but I see no further info
> there to understand what those letters actually mean.

Doesn't that mean this particular part of the bug report should be
sent to the GPG developers, asking them to clarify the GPG
documentation?  IMO, it's unreasonable to expect Emacs to rectify
documentation problems of every program we happen to invoke.

bug#34726: epa-insert-keys

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Doesn't that mean this particular part of the bug report should be
  > sent to the GPG developers, asking them to clarify the GPG
  > documentation?  IMO, it's unreasonable to expect Emacs to rectify
  > documentation problems of every program we happen to invoke.

Yes and no.  Ideally they would make it clear in the GPG documentation,
then we would make Emacs repeat that description or else make it easy
to find that from Emacs.

However, I don't know whether the GPG team includes people with those
skills and time to work on this.

I guess I will have to ask them.


-- 
Dr Richard Stallman
President, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

bug#34726: epa-insert-keys

[Lars Ingebrigtsen]

Robert Pluim <rpluim@gmail.com> writes:

>     rms> I think we should include a cleaned-up and clarified version
>     rms> of this table in those two commands' doc strings.
>
> Thatʼs not a path Iʼd want to go down. The gpg documentation is long
> and complex, because itʼs a complex program. Attempting to summarise
> it in a few docstrings will result in incomplete or possibly incorrect
> information, Iʼd rather people read the original.

That's true, but epg already does an interpretation of those status
characters and then fontifies the buffer based on them:

(defvar epg-key-validity-alist
  '((?o . unknown)
    (?i . invalid)
    (?d . disabled)
    (?r . revoked)
    (?e . expired)
    (?- . none)
    (?q . undefined)
    (?n . never)
    (?m . marginal)
    (?f . full)
    (?u . ultimate)))

To not then actually tell the users what we've interpreted the
characters to means just seems odd.

I've now changed this in Emacs 28 so that hovering over the character
says what the validity is (i.e., the help-echo property).

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no