bug#64154: Fwd: Some additions to the EasyPG Assistant's manual

[Jens Schmidt via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>]

-------- Forwarded Message --------
Subject: Re: Some additions to the EasyPG Assistant's manual
Date: Sat, 17 Jun 2023 10:44:08 +0300
From: Eli Zaretskii <eliz@gnu.org>
To: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
CC: emacs-devel@gnu.org

> Date: Sun, 11 Jun 2023 20:00:12 +0200
> From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
> 
> Hi,
> 
> I have been setting up GnuPG for Emacs/EPA lately for transparent file
> encryption and decryption, and done so for the first time.  I've
> condensed my experiences in some additions to the EPA texi file, see 
> attached patch.  Of course, such experiences are highly personal, but at 
> least on Stackoverflow others have been struggling with the same issues 
> as I did ...
> 
> This patch still needs some brushing up, and some splitting up probably
> as well.  It is based on emacs-29.

Please in the future post patches via "M-x report-emacs-bug".

> +You can use EasyPG Assistant without any Emacs or GnuPG configuration
> +whatsoever, for example to encrypt and decrypt files automatically
> +with symmetric encryption, @xref{Encrypting/decrypting gpg files}.
                               ^^^^^
You want "see @ref" here, not @xref.  The latter is only pertinent at
the beginning of a sentence, because it produces a capitalized "See".

> +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 new buffer
> +@file{*Keys*} where you can select recipients for encryption.

I don't think "new" is right here: Emacs generally reuses buffers that
already exist.  I'd drop "new" there.

> +@xref{Key management} for a description of the format of that buffer.
                         ^
Comma missing there.  Some old version of Texinfo need it.

> +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.

> +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
                                                  ^
A comma is missing there.

> +also use some free-form string that gives information on the use of
> +the keypair, like @code{backup} or @code{account database}.} you can
                                                                ^
Another comma missing there.

> +encryption for that file.  Since encryption is performed with your
> +public key, no passphrase is prompted for the buffer save, but you
> +will be prompted for your passphrase for file reads every now and
> +then, depending on the gpg-agent cache configuration.

Passive voice alert!

> +@xref{Caching Passphrases} for more information.
                              ^
Comma after the closing brace is missing.

> +As of June 2023, there are three active branches of GnuPG: 2.4,
> +2.2, and 1.4.  All those branches should work flawlessly with Emacs
>  with basic use-cases.  They have, however, some incompatible
>  characteristics, which might be visible when used from Emacs.

Given the known issues with GnuPG 2.4.1, do we need to say something
about that here?

> +@node GnuPG Pinentry
> +@chapter GnuPG Pinentry

Pleased add an index entry for the subject of this chapter.  In
general, it is a good idea to have an index entry for each
chapter/section/subsection naming is main subject.

> +@enumerate
> +@item Use Emacs only for GnuPG requests that are triggered by Emacs itself,
> +@item use Emacs for all GnuPG requests, or
> +@item use Emacs for all GnuPG requests with other Pinentry as fallback.

The capitalization if these items is inconsistent.

> +FIXME: Brush the following paragraphs up.

??

> +1.: Ensure allow-loopback-pinentry is is configured for the GPG agent,
> +which should be the default.  Configure epg-pinentry-mode to
> +`loopback.
> +
> +2.: Make pinentry-emacs the default pinentry by means of your
> +operating system.  Install package pinentry from GNU ELPA and execute
> +M-x pinentry-start to start the Pinentry service.  All GnuPG
> +passphrase requests should result in a minibuffer prompt in the
> +running Emacs.  If Emacs or pinentry service are not running,
> +passphrase requests fail.
> +
> +3.: Ensure other Pinentry supports Emacs prompt.  pinentry-curses
> +does, for example.  Configure option allow-emacs-pinentry in
> +gpg-agent.conf.  Set environment variable INSIDE_EMACS for the calling
> +process.  Install package pinentry.  Now if Emacs is running and
> +pinentry-start has been exeucted, all GnuPG passphrase requests should
> +result in a minibuffer prompt in the running Emacs.  If Emacs or
> +Pinentry service are not running, GnuPG uses the regular Pinentry
> +instead.
> +
> +First alternative can be configured in addition to onw of the others:
> +Requests triggered from within Emacs (like opening a gpg-encrypted
> +file) are handled through loopback pinentry, Requests outside of emacs
> +through pinentry feature.
> +
> +Note that the selection of a concrete Pinentry program determines only
> +@emph{how} GnuPG queries for passphrases and not @emph{how often}.
> +For the latter question @xref{Caching Passphrases}.

This doesn't seem to be finalized?

> +need to re-enter the passphrase occasionally.  However, the
> +configuration is a bit confusing since it depends on your GnuPG
> +installation @xref{GnuPG version compatibility}, encryption method
                 ^^^^^
Here, a @pxref in parentheses is TRT.

Thanks.