From 6897ace9916020e086f622e721f47a7fae8614b9 Mon Sep 17 00:00:00 2001 From: Jens Schmidt 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