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.