Subject: bug#65603: closed (Re: bug#65603: 29.1.50; [PATCH] Improve some EPG docstrings)

From: [email-masked] (GNU bug Tracking System)
Date: Thu, 07 Sep 2023 09:28:02 +0000

Your bug report

#65603: 29.1.50; [PATCH] Improve some EPG docstrings

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
65603: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=65603
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#65603: 29.1.50; [PATCH] Improve some EPG docstrings
From: Eli Zaretskii <[email-masked]>
To: Jens Schmidt <[email-masked]>
Cc: [email-masked]
Date: Thu, 07 Sep 2023 12:26:34 +0300
List-Id: <debbugs-submit.debbugs.gnu.org>

> Date: Thu, 7 Sep 2023 10:38:34 +0200
> From:  Jens Schmidt via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <[email-masked]>
> 
> Bump.  And:
> 
> On 2023-08-29  23:16, Jens Schmidt wrote:
> 
> > Please check.  Thanks.
> 
> "Please check" == "Please consider for committing on emacs-29".

Thanks, installed on emacs-29 and closing the bug.

Subject: 29.1.50; [PATCH] Improve some EPG docstrings
From: Jens Schmidt <[email-masked]>
To: [email-masked]
Date: Tue, 29 Aug 2023 23:16:52 +0200
List-Id: <debbugs-submit.debbugs.gnu.org>

While working on bug#63627 I came across some issues in EPG docstrings,
plus the challenge to use function `epg-edit-key' without any example
whatsoever.  Here are two patches that should rectify this.

Please check.  Thanks.

From 7549bef3f49b8600290ad78552329394acf99476 Mon Sep 17 00:00:00 2001
From: Jens Schmidt <[email-masked]>
Date: Tue, 29 Aug 2023 22:14:48 +0200
Subject: [PATCH 1/2] Update GnuPG-version-dependent information in docstring

* lisp/epg.el (epg-context-set-passphrase-callback): Update
GnuPG-version-dependent information in docstring and refer to Info
node `(epa)' for details.
---
 lisp/epg.el | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/lisp/epg.el b/lisp/epg.el
index 9da5a36ba3d..7add3dcd173 100644
--- a/lisp/epg.el
+++ b/lisp/epg.el
@@ -266,11 +266,11 @@ epg-context-set-passphrase-callback
 The function gets three arguments: the context, the key-id in
 question, and the callback data (if any).

-The callback may not be called if you use GnuPG 2.x, which relies
-on the external program called `gpg-agent' for passphrase query.
-If you really want to intercept passphrase query, consider
-installing GnuPG 1.x _along with_ GnuPG 2.x, which does passphrase
-query by itself and Emacs can intercept them."
+The callback may not be called if you use GnuPG 2.0, which relies
+only on external programs for passphrase query and does not
+provide loopback pinentry.  For details see Info node `(epa)
+GnuPG version compatibility' and Info node `(epa) GnuPG
+Pinentry'."
   ;; (declare (obsolete setf "25.1"))
   (setf (epg-context-passphrase-callback context)
         (if (functionp passphrase-callback)
--
2.30.2
From 6897ace9916020e086f622e721f47a7fae8614b9 Mon Sep 17 00:00:00 2001
From: Jens Schmidt <[email-masked]>
Date: Tue, 29 Aug 2023 23:03:36 +0200
Subject: [PATCH 2/2] Improve docstrings and provide an example

* lisp/epg.el (epg-start-edit-key): Replace description of arguments
by a reference to `epg-edit-key'.
(epg-edit-key): More precisely describe callback operation and
arguments and provide an example of how to edit a key.
---
 lisp/epg.el | 46 ++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 42 insertions(+), 4 deletions(-)

diff --git a/lisp/epg.el b/lisp/epg.el
index 7add3dcd173..ed29f08a08f 100644
--- a/lisp/epg.el
+++ b/lisp/epg.el
@@ -2019,9 +2019,7 @@ epg-generate-key-from-string
 (defun epg-start-edit-key (context key edit-callback handback)
   "Initiate an edit operation on KEY.
 
-EDIT-CALLBACK is called from process filter and takes four
-arguments: the context, a status, an argument string, and the
-handback argument.
+See `epg-edit-key' for a description of the arguments.
 
 If you use this function, you will need to wait for the completion of
 `epg-gpg-program' by using `epg-wait-for-completion' and call
@@ -2036,7 +2034,47 @@ epg-start-edit-key
 			     (car (epg-key-sub-key-list key))))))
 
 (defun epg-edit-key (context key edit-callback handback)
-  "Edit KEY in the keyring."
+  "Edit KEY in the keyring.
+
+This function and function `epg-start-edit-key' use the
+line-based protocol enabled by \"gpg\" parameter \"--status-fd\"
+to edit KEY.  For each GnuPG status line, these functions or,
+more precisely, the EPG process filter calls EDIT-CALLBACK with
+four arguments: argument CONTEXT, the GnuPG status keyword, the
+GnuPG status argument string, and argument HANDBACK.
+
+The following example uses a simple state machine to trust the
+first subkey of key KEY ultimately:
+
+  (let ((state 0))
+    (epg-edit-key
+     context key
+     (lambda (context status string _handback)
+       (pcase (vector state status string)
+         (\\=`[0  \"KEY_CONSIDERED\" ,_])
+         (\\='[1  \"GET_LINE\" \"keyedit.prompt\"]
+          (process-send-string (epg-context-process context) \"1\\n\"))
+         (\\='[2  \"GOT_IT\" \"\"])
+         (\\='[3  \"GET_LINE\" \"keyedit.prompt\"]
+          (process-send-string (epg-context-process context) \"trust\\n\"))
+         (\\='[4  \"GOT_IT\" \"\"])
+         (\\='[5  \"GET_LINE\" \"edit_ownertrust.value\"]
+          (process-send-string (epg-context-process context) \"5\\n\"))
+         (\\='[6  \"GOT_IT\" \"\"])
+         (\\='[7  \"GET_BOOL\" \"edit_ownertrust.set_ultimate.okay\"]
+          (process-send-string (epg-context-process context) \"yes\\n\"))
+         (\\='[8  \"GOT_IT\" \"\"])
+         (\\='[9  \"GET_LINE\" \"keyedit.prompt\"]
+          (process-send-string (epg-context-process context) \"quit\\n\"))
+         (\\='[10 \"GOT_IT\" \"\"])
+         (_
+          (error \"Key edit protocol error in state %d\" state)))
+       (setq state (1+ state)))
+     nil))
+
+This is a slightly simplified example: Ideally, it should have
+double-checked the fingerprint argument to the \"KEY_CONSIDERED\"
+status keyword instead of ignoring it."
   (unwind-protect
       (progn
 	(epg-start-edit-key context key edit-callback handback)
-- 
2.30.2