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

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

[Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors]

[-- Attachment #1: Type: text/plain, Size: 225 bytes --]

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.

[-- Attachment #2: 0001-Update-GnuPG-version-dependent-information-in-docstr.patch --]
[-- Type: text/x-patch, Size: 1465 bytes --]

From 7549bef3f49b8600290ad78552329394acf99476 Mon Sep 17 00:00:00 2001
From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
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

[-- Attachment #3: 0002-Improve-docstrings-and-provide-an-example.patch --]
[-- Type: text/x-patch, Size: 3291 bytes --]

From 6897ace9916020e086f622e721f47a7fae8614b9 Mon Sep 17 00:00:00 2001
From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
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

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

[Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Bump.  And:

On 2023-08-29  23:16, Jens Schmidt wrote:

> Please check.  Thanks.

"Please check" == "Please consider for committing on emacs-29".

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

[Eli Zaretskii]

> 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" <bug-gnu-emacs@gnu.org>
> 
> 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.