From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#64154: Some additions to the EasyPG Assistant's manual Date: Sun, 09 Jul 2023 10:24:37 +0300 Message-ID: <83a5w5bl8q.fsf@gnu.org> References: <83wn02r0s7.fsf@gnu.org> <26dac916-117c-d8a1-ad97-0e3e9313ff71@vodafonemail.de> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="25833"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 64154@debbugs.gnu.org To: Jens Schmidt Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sun Jul 09 09:25:23 2023 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1qIOnL-0006Wq-7d for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 09 Jul 2023 09:25:23 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qIOn6-0003kX-3j; Sun, 09 Jul 2023 03:25:08 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qIOn0-0003kC-IB for bug-gnu-emacs@gnu.org; Sun, 09 Jul 2023 03:25:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qIOn0-0002tv-9F for bug-gnu-emacs@gnu.org; Sun, 09 Jul 2023 03:25:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1qIOmz-0000ME-M3 for bug-gnu-emacs@gnu.org; Sun, 09 Jul 2023 03:25:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 09 Jul 2023 07:25:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 64154 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 64154-submit@debbugs.gnu.org id=B64154.16888874821336 (code B ref 64154); Sun, 09 Jul 2023 07:25:01 +0000 Original-Received: (at 64154) by debbugs.gnu.org; 9 Jul 2023 07:24:42 +0000 Original-Received: from localhost ([127.0.0.1]:45687 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qIOmf-0000LQ-Nx for submit@debbugs.gnu.org; Sun, 09 Jul 2023 03:24:42 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:53326) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qIOma-0000L9-Vn for 64154@debbugs.gnu.org; Sun, 09 Jul 2023 03:24:40 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qIOmV-0002r1-Ex; Sun, 09 Jul 2023 03:24:31 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=FvsvWRaZC8WE35W5zZXxngxGDfx2KlNgorMWWwmmHcA=; b=lf7jluAOHfqH xIVo8KMTxpH3+mDlPbCzGNsf+brIad40nKoXW8VUzVQAftAngM27TmvC073Tv0CTyOIFRscKt0ICL Rol4qF7EM082YUB99nEdvEnaPEwY96K1aoc4q8pI0qJx+vidiRjLVHXiem1VjpALBp3j+gNvUTU7M ztgMiINWgEuPOY0woY302BwGglhtupM9PEYc68GEmCwZUz0Sp2mTRiYacifiDaFR0nrq+lJ9EGoou zZHogVDXxfS7M3FA3JE/hxcmczqxzhbAPifTVxwb9HZznen740YXWi3JmuPTd+b64UO/Mzc0pMwdg 01tZX0Qo43e1fLR8Qzh7ow==; Original-Received: from [87.69.77.57] (helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qIOmU-0005C0-Vb; Sun, 09 Jul 2023 03:24:31 -0400 In-Reply-To: <26dac916-117c-d8a1-ad97-0e3e9313ff71@vodafonemail.de> (message from Jens Schmidt on Sat, 8 Jul 2023 22:31:16 +0200) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.bugs:264820 Archived-At: > Date: Sat, 8 Jul 2023 22:31:16 +0200 > From: Jens Schmidt > Cc: 64154@debbugs.gnu.org > > So after setting up the concept index, here comes what I originally > intended to add to epa.texi. Plus my comments on you first review > (https://debbugs.gnu.org/cgi/bugreport.cgi?bug=64154#8) where I have > additional questions. Unless otherwise stated I followed your > recommendations, however. Thanks. > >> +@xref{Key management} for a description of the format of that > >> buffer. > > ^ > > Comma missing there. Some old version of Texinfo need it. > > I changed these as you have proposed. But TBH I find that comma rather > disturbing. This might be a non-native speaker's view, but isn't then > > "See @ref{Key management} for a description ... > > easier to read *and* clearer in the texi file? Or, IOW, do we *have* to > use @xref at the beginning of sentences because it has some other nice > properties? It doesn't matter whether you use @xref or @ref, they both should be followed by some punctuation, either a comma or a period, if we want to support those older versions of Texinfo which insisted on that. > Same question for @pxref? @pxref is different, in that it doesn't need such punctuation. Which is why it is pertinent only in some contexts. > >> +You can streamline this recipient selection step by customizing > >> +variables @code{epa-file-encrypt-to} and @code{epa-file-select-keys}, > >> +see below. > > > > Instead of "see below", please add a cross-reference to the node where > > these variables are documented. > > Actually, here "see below" refers to the same node. Then disregard my comment, I was under the impression that you refer to a different node. > +John Michael Ashley's GNU Privacy Handbook, available online as part > +of @uref{https://gnupg.org/documentation/guides.html, the GnuPG user > +guides}, provides an introduction to GnuPG use and configuration. In > +contrast to that, the GnuPG manual (@pxref{Top, , Top, gnupg, Using > +the GNU Privacy Guard}) is more of of a reference manual. ^^^^^ Redundant "of" there. > +When you save a buffer, say, to file @file{foo.gpg} for the first > +time, EasyPG Assistant presents you a list of keys in a buffer The reference to the file's name here is not necessary, and just makes the text harder to read. This simpler variant doesn't seem to lose any useful content: When you save a buffer to an encrypted file for the first time, EasyPG Assistant presents you a list of keys in a buffer ... > +reads, since the gpg-agent caches your passphrase for file reads at > +least for some time, but not for buffer saves. I think gpg-agent should be in @command (here and elsewhere), since it's a shell command name. Also, perhaps a cross-reference to the GPG documentation that describes gpg-agent would be appropriate here? > +@cindex public key encryption, passphrase entry for > +If you have created your own keypair@footnote{For encryption and > +decryption of files you do not intend to share, you do not have to use > +an email address as recipient during creation of the keypair. You can > +also use some free-form string that gives information on the use of > +the keypair, like @code{backup} or @code{account database}.}, you can > +select that as recipient, and EasyPG Assistant uses public key > +encryption for that file. ^^^^ Probably "will use" there is better? > +@cindex tempory files created by easypg assistant > +To encrypt and decrypt files as described above EasyPG Assistant under > +certain circumstances uses intermediate tempory files that contain the > +plain-text contents of the files it processes. EasyPG Assistant > +creates them below the directory returned by function > +@code{temporary-file-directory}. I think a cross-reference to the place in ELisp manual, where temporary-file-directory is described, will be useful here. > For frequently visited files, it might be a good idea to tell Emacs > -which encryption method should be used through @xref{File Variables, , > -, emacs, the Emacs Manual}. Use the @code{epa-file-encrypt-to} local > -variable for this. > +which encryption method should be used through file variables > +(@pxref{File Variables, , Local Variables in Files, emacs, The Emacs > +Editor}). Use the @code{epa-file-encrypt-to} local variable for this. > @vindex epa-file-encrypt-to This @vindex entry should be before the text describing the variable, not after it. > @@ -478,6 +532,11 @@ Encrypting/decrypting gpg files > @defvar epa-file-cache-passphrase-for-symmetric-encryption > If non-@code{nil}, cache passphrase for symmetric encryption. The > default value is @code{nil}. > + > +For security reasons, this option is turned off by default and not > +recommended to use. ^^^^^^^^^^^^^^^^^^ Either "not recommended for use" or "not recommended to be used". > +@cindex loopback pinentry > +This so called loopback Pinentry has the added benefit that it works This introduces terminology, so it should use @dfn: This so-called @dfn{loopback Pinentry} has the added benefit ... > +also when you use Emacs remotely or from a text-only terminal. To > +enable it: > + > +@enumerate > +@item > +Ensure that option @code{allow-loopback-pinentry} is configured for > +gpg-agent, which should be the default. > + > +@item > +Customize variable @code{epg-pinentry-mode} to @code{loopback} in > +Emacs. > +@end enumerate Shouldn't the two variables mentioned here be indexed? If they are already indexed, but the index entries point to another place, having a cross-reference here to that place is TRT. > +@c In case somebody requests these: It is better to use @ignore...@end ignore instead of commenting out. > +@c Make pinentry-emacs the default Pinentry by means of your operating > +@c system. Install package pinentry.el from GNU ELPA and execute M-x > +@c pinentry-start to start the Emacs Pinentry service. *All* GnuPG "M-x command" should be in @kbd.