* bug#65603: 29.1.50; [PATCH] Improve some EPG docstrings
@ 2023-08-29 21:16 Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-09-07 8:38 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
0 siblings, 1 reply; 3+ messages in thread
From: Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2023-08-29 21:16 UTC (permalink / raw)
To: 65603
[-- 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
^ permalink raw reply related [flat|nested] 3+ messages in thread
* bug#65603: 29.1.50; [PATCH] Improve some EPG docstrings
2023-08-29 21:16 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
@ 2023-09-07 8:38 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-09-07 9:26 ` Eli Zaretskii
0 siblings, 1 reply; 3+ messages in thread
From: Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2023-09-07 8:38 UTC (permalink / raw)
To: 65603
Bump. And:
On 2023-08-29 23:16, Jens Schmidt wrote:
> Please check. Thanks.
"Please check" == "Please consider for committing on emacs-29".
^ permalink raw reply [flat|nested] 3+ messages in thread
* bug#65603: 29.1.50; [PATCH] Improve some EPG docstrings
2023-09-07 8:38 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2023-09-07 9:26 ` Eli Zaretskii
0 siblings, 0 replies; 3+ messages in thread
From: Eli Zaretskii @ 2023-09-07 9:26 UTC (permalink / raw)
To: Jens Schmidt; +Cc: 65603-done
> 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.
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2023-09-07 9:26 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-08-29 21:16 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
2023-09-07 8:38 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-09-07 9:26 ` Eli Zaretskii
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).