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

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]

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

bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi

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

On 2023-06-18  19:32, Eli Zaretskii wrote:

Back from greener pastures, sorry for the delay.

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

Problem here being that epa.texi has no concept index yet.  Should I
create one from the existing chapters/sections/subsections in a separate
patch?

And the next question is: Does this ("new documentation of existing 
features") qualify for Emacs 29?

Thanks

bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi

[Eli Zaretskii]

> Date: Thu, 29 Jun 2023 23:10:41 +0200
> From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
> Cc: 64154@debbugs.gnu.org
> 
> On 2023-06-18  19:32, Eli Zaretskii wrote:
> 
> Back from greener pastures, sorry for the delay.
> 
> >> +@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.
> 
> Problem here being that epa.texi has no concept index yet.  Should I
> create one from the existing chapters/sections/subsections in a separate
> patch?

Yes, please.  A manual that lacks Concept Index is not a good manual,
IMO.  In fact, Concept Index should be the very first index in a
manual; there are some good manuals which have only that and nothing
else.

> And the next question is: Does this ("new documentation of existing 
> features") qualify for Emacs 29?

Documentation improvements and fixes are always okay on the release
branch.  (But please hurry, since I plan on releasing Emacs 29.1 soon,
barring any grave bugs that will be uncovered.)

Thanks.

bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi

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

On 2023-06-30  07:54, Eli Zaretskii wrote:

> Yes, please.  A manual that lacks Concept Index is not a good manual,
> IMO.  In fact, Concept Index should be the very first index in a
> manual; there are some good manuals which have only that and nothing
> else.

Another such possible systematic update I could do while touching 
things: Consistently title-casing node names and/or chapter/section 
titles.  OK or not OK?  I'm not sure about external references if case 
changes.

Thanks

bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi

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

On 2023-06-30  21:13, Jens Schmidt wrote:
> On 2023-06-30  07:54, Eli Zaretskii wrote:
> 
>> Yes, please.  A manual that lacks Concept Index is not a good manual,
>> IMO.  In fact, Concept Index should be the very first index in a
>> manual; there are some good manuals which have only that and nothing
>> else.
> 
> Another such possible systematic update I could do while touching 
> things: Consistently title-casing node names and/or chapter/section 
> titles.  OK or not OK?  I'm not sure about external references if case 
> changes.

Just found this in the texinfo manual:

    * Case is significant in node names.

Will keep the node names untouched, but title-case the hierarchy.

bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi

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

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

On 2023-06-30  07:54, Eli Zaretskii wrote:

>>> Yes, please.  A manual that lacks Concept Index is not a good
>>> manual, IMO.  In fact, Concept Index should be the very first
>>> index in a manual; there are some good manuals which have only
>>> that and nothing else.

Here you go: Concept index added, structure titles title-cased.  Please
check.

Thanks

[-- Attachment #2: 0001-Add-concept-index-title-case-structure-titles.patch --]
[-- Type: text/x-patch, Size: 9013 bytes --]

From 4c3a7660acda89a542fc8916d5125dc3c83bf961 Mon Sep 17 00:00:00 2001
From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
Date: Fri, 30 Jun 2023 22:20:57 +0200
Subject: [PATCH] Add concept index, title-case structure titles

* doc/misc/epa.texi (Top, Overview, Quick start, Commands)
(Key management, Cryptographic operations on regions)
(Cryptographic operations on files, Dired integration)
(Mail-mode integration, Encrypting/decrypting gpg files)
(Querying a key server, GnuPG version compatibility, Caching Passphrases)
(GNU Free Documentation License): Add concept index, title-case
structure titles.  (Bug#64154)
---
 doc/misc/epa.texi | 85 +++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 74 insertions(+), 11 deletions(-)

diff --git a/doc/misc/epa.texi b/doc/misc/epa.texi
index 6f63a3d7ba0..c59f9b8630e 100644
--- a/doc/misc/epa.texi
+++ b/doc/misc/epa.texi
@@ -43,7 +43,11 @@
 @contents
 
 @node Top
-@top EasyPG Assistant user's manual
+@top EasyPG Assistant User's Manual
+@cindex easypg assistant
+@cindex easypg
+@cindex gnu privacy guard
+@cindex gnupg
 
 EasyPG Assistant is an Emacs user interface to GNU Privacy Guard
 (GnuPG, @pxref{Top, , Top, gnupg, Using the GNU Privacy Guard}).
@@ -56,6 +60,12 @@ Top
 @insertcopying
 @end ifnottex
 
+@c Unfortunately the node names of this manual are not very consistent
+@c w.r.t. their case.  However, case is significant in node names, so
+@c we probably better should not change these to not break any
+@c external references.  Things are more relaxed for structure titles,
+@c so we consistently updated them to title-case.
+
 @menu
 * Overview::
 * Quick start::
@@ -64,6 +74,7 @@ Top
 * Caching Passphrases::
 * Bug Reports::
 * GNU Free Documentation License::  The license for this documentation.
+* Concept Index::
 * Key Index::
 * Function Index::
 * Variable Index::
@@ -71,6 +82,9 @@ Top
 
 @node Overview
 @chapter Overview
+@cindex overview
+@cindex feature overview
+@cindex features
 
 EasyPG Assistant provides the following features.
 
@@ -84,7 +98,9 @@ Overview
 @end itemize
 
 @node Quick start
-@chapter Quick start
+@chapter Quick Start
+@cindex quick start
+@cindex introduction
 
 EasyPG Assistant commands are prefixed by @samp{epa-}.  For example,
 
@@ -104,6 +120,7 @@ Quick start
 
 @node Commands
 @chapter Commands
+@cindex commands
 
 This chapter introduces various commands for typical use cases.
 
@@ -118,7 +135,11 @@ Commands
 @end menu
 
 @node Key management
-@section Key management
+@section Key Management
+@cindex key management
+@cindex key ring
+
+@cindex browse key ring
 Probably the first step of using EasyPG Assistant is to browse your
 keyring.  @kbd{M-x epa-list-keys} is corresponding to @samp{gpg
 --list-keys} from the command line.
@@ -157,6 +178,7 @@ Key management
         Fingerprint: 9003 D76B 73B7 4A8A E588  10AF 4447 461B 2A9B EA2D
 @end example
 
+@cindex browse private key ring
 @noindent
 To browse your private keyring, use @kbd{M-x epa-list-secret-keys}.
 
@@ -172,12 +194,14 @@ Key management
 Below are other commands related to key management.  Some of them take
 a file as input/output, and others take the current region.
 
+@cindex insert key
 @deffn Command epa-insert-keys keys
 Insert selected @var{keys} after the point.  It will let you select
 keys before insertion.  By default, it will encode keys in the OpenPGP
 armor format.
 @end deffn
 
+@cindex import key
 @deffn Command epa-import-keys file
 Import keys from @var{file} to your keyring.
 @end deffn
@@ -195,14 +219,18 @@ Key management
 applies @code{epa-import-keys-region} to each of them.
 @end deffn
 
+@cindex delete key
 @deffn Command epa-delete-keys allow-secret
 Delete selected keys.  If @var{allow-secret} is non-@code{nil}, it
 also delete the secret keys.
 @end deffn
 
 @node Cryptographic operations on regions
-@section Cryptographic operations on regions
+@section Cryptographic Operations on Regions
+@cindex cryptographic operations on regions
+@cindex region operations
 
+@cindex decrypt region
 @deffn Command epa-decrypt-region start end
 Decrypt the current region between @var{start} and @var{end}.  It
 replaces the region with the decrypted text.
@@ -216,6 +244,7 @@ Cryptographic operations on regions
 command does not alter the original text around armors.
 @end deffn
 
+@cindex verify region
 @deffn Command epa-verify-region start end
 Verify the current region between @var{start} and @var{end}.  It sends
 the verification result to the minibuffer or a popup window.  It
@@ -231,6 +260,7 @@ Cryptographic operations on regions
 not alter the original text around OpenPGP cleartext blocks.
 @end deffn
 
+@cindex sign region
 @deffn Command epa-sign-region start end signers type
 Sign the current region between @var{start} and @var{end}.  By
 default, it creates a cleartext signature.  If a prefix argument is
@@ -238,6 +268,7 @@ Cryptographic operations on regions
 type.
 @end deffn
 
+@cindex encrypt region
 @deffn Command epa-encrypt-region start end recipients sign signers
 Encrypt the current region between @var{start} and @var{end}.  It will
 let you select recipients.  If a prefix argument is given, it will
@@ -246,28 +277,37 @@ Cryptographic operations on regions
 @end deffn
 
 @node Cryptographic operations on files
-@section Cryptographic operations on files
+@section Cryptographic Operations on Files
+@cindex cryptographic operations on files
+@cindex file operations
 
+@cindex decrypt file
 @deffn Command epa-decrypt-file file &optional output
 Decrypt @var{file}.  If you do not specify the name @var{output} to
 use for the decrypted file, this function prompts for the value to use.
 @end deffn
 
+@cindex verify file
 @deffn Command epa-verify-file file
 Verify @var{file}.
 @end deffn
 
+@cindex sign file
 @deffn Command epa-sign-file file signers type
 Sign @var{file}.  If a prefix argument is given, it will let you
 select signing keys, and then a signature type.
 @end deffn
 
+@cindex encrypt file
 @deffn Command epa-encrypt-file file recipients
 Encrypt @var{file}.  It will let you select recipients.
 @end deffn
 
 @node Dired integration
-@section Dired integration
+@section Dired Integration
+@cindex dired integration
+@cindex directory operations
+@cindex multiple file operations
 
 EasyPG Assistant extends Dired Mode for GNU Emacs to allow users to
 easily do cryptographic operations on files.  For example,
@@ -306,7 +346,10 @@ Dired integration
 @end table
 
 @node Mail-mode integration
-@section Mail-mode integration
+@section Mail-Mode Integration
+@cindex mail-mode integration
+@cindex sending signed mails
+@cindex sending encrypted mails
 
 EasyPG Assistant provides a minor mode @code{epa-mail-mode} to help
 user compose inline OpenPGP messages.  Inline OpenPGP is a traditional
@@ -361,7 +404,12 @@ Mail-mode integration
 @end table
 
 @node Encrypting/decrypting gpg files
-@section Encrypting/decrypting gpg files
+@section Encrypting and Decrypting gpg Files
+@cindex encrypting gpg files
+@cindex decrypting gpg files
+@cindex gpg files
+@cindex automatic file encryption and decryption
+
 By default, every file whose name ends with @file{.gpg} will be
 treated as encrypted.  That is, when you open such a file, the
 decrypted text is inserted in the buffer rather than encrypted one.
@@ -444,7 +492,10 @@ Encrypting/decrypting gpg files
 @end defvar
 
 @node Querying a key server
-@section Querying a key server
+@section Querying a Key Server
+@cindex querying key server
+@cindex query key server
+@cindex key server
 
 The @code{epa-search-keys} command can be used to query a
 @acronym{GPG} key server.  Emacs will then pop up a buffer that lists
@@ -457,9 +508,11 @@ Querying a key server
 
 The @code{epa-keyserver} variable says which server to query.
 
-
 @node GnuPG version compatibility
-@chapter GnuPG version compatibility
+@chapter GnuPG Version Compatibility
+@cindex gnupg version compatibility
+@cindex version compatibility
+@cindex compatibility
 
 As of February 2016, there are three active branches of GnuPG: 2.1,
 2.0, and 1.4.  All those branches should work flawlessly with Emacs
@@ -492,6 +545,10 @@ GnuPG version compatibility
 
 @node Caching Passphrases
 @chapter Caching Passphrases
+@cindex caching passphrases
+@cindex entering passphrases
+@cindex passphrase cache
+@cindex passphrases
 
 Typing passphrases is a troublesome task if you frequently open and
 close the same file.  GnuPG and EasyPG Assistant provide mechanisms to
@@ -532,6 +589,8 @@ Caching Passphrases
 
 @node Bug Reports
 @chapter Bug Reports
+@cindex bug reports
+@cindex reporting bugs
 
 Bugs and problems with EasyPG Assistant are actively worked on by the
 Emacs development team.  Feature requests and suggestions are also
@@ -556,6 +615,10 @@ GNU Free Documentation License
 @appendix GNU Free Documentation License
 @include doclicense.texi
 
+@node Concept Index
+@unnumbered Concept Index
+@printindex cp
+
 @node Key Index
 @unnumbered Key Index
 @printindex ky
-- 
2.30.2

bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi

[Eli Zaretskii]

> Date: Fri, 30 Jun 2023 22:54:11 +0200
> From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
> Cc: 64154@debbugs.gnu.org
> 
> >>> Yes, please.  A manual that lacks Concept Index is not a good
> >>> manual, IMO.  In fact, Concept Index should be the very first
> >>> index in a manual; there are some good manuals which have only
> >>> that and nothing else.
> 
> Here you go: Concept index added, structure titles title-cased.  Please
> check.

Thanks, see some comments below.

>  @node Top
> -@top EasyPG Assistant user's manual
> +@top EasyPG Assistant User's Manual
> +@cindex easypg assistant
> +@cindex easypg

It is not useful to have several index entries starting with the same
substring and pointing to the same place.  For example, here, you only
need "@cindex easypg assistant", the "@cindex easypg" one is redundant.

> +@cindex overview
> +@cindex feature overview
> +@cindex features

Likewise here.  Moreover, these index entries are too general.  Think
about the case of someone doing "M-x info-apropos", in which case they
get index entries from many different manuals.  Thus

  @cindex easypg assistant features

is more useful.

>  @node Quick start
> -@chapter Quick start
> +@chapter Quick Start
> +@cindex quick start
> +@cindex introduction

Same here: "introduction to easypg assistant" is more useful.

>  @node Commands
>  @chapter Commands
> +@cindex commands

And here, and elsewhere in this manual.

>  @node Key management
> -@section Key management
> +@section Key Management
> +@cindex key management
> +@cindex key ring
> +
> +@cindex browse key ring

The "@cindex key ring" is redundant, given the other two.

> +@cindex browse private key ring
>  @noindent
>  To browse your private keyring, use @kbd{M-x epa-list-secret-keys}.

Here, I'd use "@cindex private key ring", unless that rin is described
in another section.

> +@cindex insert key
>  @deffn Command epa-insert-keys keys

"@cindex insert keys" is better.

> +@cindex import key
>  @deffn Command epa-import-keys file

Likewise here: "keys".

> +@cindex delete key
>  @deffn Command epa-delete-keys allow-secret

And here.

>  @node Cryptographic operations on files
> -@section Cryptographic operations on files
> +@section Cryptographic Operations on Files
> +@cindex cryptographic operations on files
> +@cindex file operations

I'd change the last one to "@cindex file operations, cryptographic",
to make it less general.

>  @node Mail-mode integration
> -@section Mail-mode integration
> +@section Mail-Mode Integration
> +@cindex mail-mode integration
> +@cindex sending signed mails
> +@cindex sending encrypted mails

I'd make one index entry from the last two:

  @cindex sending encrypted/signed mails

>  @node Querying a key server
> -@section Querying a key server
> +@section Querying a Key Server
> +@cindex querying key server
> +@cindex query key server
> +@cindex key server

I'd keep only the first index entry here, the other two are redundant.

>  @node GnuPG version compatibility
> -@chapter GnuPG version compatibility
> +@chapter GnuPG Version Compatibility
> +@cindex gnupg version compatibility
> +@cindex version compatibility
> +@cindex compatibility

Likewise here.  You need to remember that typing "i compatibility" in
the Info reader will find the "gnupg version compatibility" entry,
because Info-index uses substring search in the indices.

>  @node Caching Passphrases
>  @chapter Caching Passphrases
> +@cindex caching passphrases
> +@cindex entering passphrases
> +@cindex passphrase cache
> +@cindex passphrases

Here, I'd lose the "@cindex passphrase cache", as the other entries
cover it.

bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi

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

On 2023-07-01  08:01, Eli Zaretskii wrote:

> Thanks, see some comments below.

Thanks for your review.  Comments and new patch to follow, only I have a
more general question now:

How would you prefer my follow-up changes?  On top of the first patch
(so you can more easily check where I followed your recommendations and
where not) or should I rebase both commits from origin/emacs-29 into one
patch?

Another more general question: You have been asking for a hurry since
you'd like to release Emacs 29.1.  What would happen to patches coming
after that release?

bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi

[Eli Zaretskii]

> Date: Sat, 1 Jul 2023 13:13:44 +0200
> Cc: 64154@debbugs.gnu.org
> From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
> 
> How would you prefer my follow-up changes?  On top of the first patch
> (so you can more easily check where I followed your recommendations and
> where not) or should I rebase both commits from origin/emacs-29 into one
> patch?

No, on top of the current branch.

> Another more general question: You have been asking for a hurry since
> you'd like to release Emacs 29.1.  What would happen to patches coming
> after that release?

They will go into Emacs 29.2.

bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi

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

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

On 2023-07-01  08:01, Eli Zaretskii wrote:

> Thanks, see some comments below.

Thanks for the review, next version attached.  I did not follow all your
recommendations, though, since ...

> Likewise here.  You need to remember that typing "i compatibility"
> in the Info reader will find the "gnupg version compatibility"
> entry, because Info-index uses substring search in the indices.

... I don't quite agree on that one: For example, I use completion on my
index queries.  And at least with my configuration ("-Q" is different
here, agreed) I won't find "gnupg version compatibility" when I type
"comp TAB" and if there would be only

   @chapter GnuPG Version Compatibility
   @cindex gnupg version compatibility

Similar problems arise if anybody actually cares looking at the
alphabetically ordered index, be it in an online reader or in print.
(After all an index should be there for alphabetical lookup, shouldn't it?)

Also here are some examples from the Elisp reference manual which I used
as reference:

   @node Change Hooks
   @section Change Hooks
   @cindex change hooks
   @cindex hooks for text changes

   @node Checksum/Hash
   @section Checksum/Hash
   @cindex MD5 checksum
   @cindex SHA hash
   @cindex hash, cryptographic
   @cindex cryptographic hash

Finally, even the Texinfo manual recommends (Index Entries(texinfo)):

   For example, one reader may think it obvious that the
   two-letter names for indices should be listed under "Indices,
   two-letter names", since "Indices" are the general concept.
   But another reader may remember the specific concept of
   two-letter names and search for the entry listed as "Two letter
   names for indices".  A good index will have both entries and
   will help both readers.

I changed some of the index entries accordingly ("A B" += "B, A"),
removing the overly generic ones.

BTW, above chapter also has a note on capitalization of index entries,
so I went for "GnuPG" and "EasyPG" in the index entries instead of all
lower-casing them.

>> +@cindex insert key
 >> +@deffn Command epa-insert-keys keys>
> "@cindex insert keys" is better.

Agreed.  However, I'm not quite sure for what reason you proposed that,
so I changed, for example

   @cindex decrypt region

to

   @cindex decrypt *a* region

and not to

   @cindex decrypt regions

Finally, I noticed that the index entries are not quite consistent 
w.r.t. tense: Some use present tense, some present continuous.  I could 
change that ...

[-- Attachment #2: 0002-Brush-up-index-entries-after-review.patch --]
[-- Type: text/x-patch, Size: 7522 bytes --]

From 9a60304d83edbb64e91e3cec60e9fba0d9ab043d Mon Sep 17 00:00:00 2001
From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
Date: Sat, 1 Jul 2023 18:51:17 +0200
Subject: [PATCH 2/2] Brush up index entries after review

* doc/misc/epa.texi (Top, Overview, Quick start, Commands)
(Key management, Cryptographic operations on regions, Dired integration)
(Encrypting/decrypting gpg files, Querying a key server)
(Caching Passphrases): Brush up index entries after review.  (Bug#64154)
---
 doc/misc/epa.texi | 64 +++++++++++++++++++++--------------------------
 1 file changed, 28 insertions(+), 36 deletions(-)

diff --git a/doc/misc/epa.texi b/doc/misc/epa.texi
index c59f9b8630e..4b998939ef5 100644
--- a/doc/misc/epa.texi
+++ b/doc/misc/epa.texi
@@ -44,10 +44,9 @@
 
 @node Top
 @top EasyPG Assistant User's Manual
-@cindex easypg assistant
-@cindex easypg
-@cindex gnu privacy guard
-@cindex gnupg
+@cindex EasyPG Assistant
+@cindex GNU Privacy Guard
+@cindex GnuPG
 
 EasyPG Assistant is an Emacs user interface to GNU Privacy Guard
 (GnuPG, @pxref{Top, , Top, gnupg, Using the GNU Privacy Guard}).
@@ -82,9 +81,7 @@ Top
 
 @node Overview
 @chapter Overview
-@cindex overview
-@cindex feature overview
-@cindex features
+@cindex features of EasyPG Assistant
 
 EasyPG Assistant provides the following features.
 
@@ -99,8 +96,7 @@ Overview
 
 @node Quick start
 @chapter Quick Start
-@cindex quick start
-@cindex introduction
+@cindex introduction to EasyPG Assistant
 
 EasyPG Assistant commands are prefixed by @samp{epa-}.  For example,
 
@@ -120,7 +116,6 @@ Quick start
 
 @node Commands
 @chapter Commands
-@cindex commands
 
 This chapter introduces various commands for typical use cases.
 
@@ -137,9 +132,9 @@ Commands
 @node Key management
 @section Key Management
 @cindex key management
-@cindex key ring
 
-@cindex browse key ring
+@cindex key ring, browsing
+@cindex browse the key ring
 Probably the first step of using EasyPG Assistant is to browse your
 keyring.  @kbd{M-x epa-list-keys} is corresponding to @samp{gpg
 --list-keys} from the command line.
@@ -178,7 +173,7 @@ Key management
         Fingerprint: 9003 D76B 73B7 4A8A E588  10AF 4447 461B 2A9B EA2D
 @end example
 
-@cindex browse private key ring
+@cindex private key ring, browsing
 @noindent
 To browse your private keyring, use @kbd{M-x epa-list-secret-keys}.
 
@@ -194,14 +189,14 @@ Key management
 Below are other commands related to key management.  Some of them take
 a file as input/output, and others take the current region.
 
-@cindex insert key
+@cindex insert keys
 @deffn Command epa-insert-keys keys
 Insert selected @var{keys} after the point.  It will let you select
 keys before insertion.  By default, it will encode keys in the OpenPGP
 armor format.
 @end deffn
 
-@cindex import key
+@cindex import keys
 @deffn Command epa-import-keys file
 Import keys from @var{file} to your keyring.
 @end deffn
@@ -219,7 +214,7 @@ Key management
 applies @code{epa-import-keys-region} to each of them.
 @end deffn
 
-@cindex delete key
+@cindex delete keys
 @deffn Command epa-delete-keys allow-secret
 Delete selected keys.  If @var{allow-secret} is non-@code{nil}, it
 also delete the secret keys.
@@ -230,7 +225,7 @@ Cryptographic operations on regions
 @cindex cryptographic operations on regions
 @cindex region operations
 
-@cindex decrypt region
+@cindex decrypt a region
 @deffn Command epa-decrypt-region start end
 Decrypt the current region between @var{start} and @var{end}.  It
 replaces the region with the decrypted text.
@@ -244,7 +239,7 @@ Cryptographic operations on regions
 command does not alter the original text around armors.
 @end deffn
 
-@cindex verify region
+@cindex verify a region
 @deffn Command epa-verify-region start end
 Verify the current region between @var{start} and @var{end}.  It sends
 the verification result to the minibuffer or a popup window.  It
@@ -260,7 +255,7 @@ Cryptographic operations on regions
 not alter the original text around OpenPGP cleartext blocks.
 @end deffn
 
-@cindex sign region
+@cindex sign a region
 @deffn Command epa-sign-region start end signers type
 Sign the current region between @var{start} and @var{end}.  By
 default, it creates a cleartext signature.  If a prefix argument is
@@ -268,7 +263,7 @@ Cryptographic operations on regions
 type.
 @end deffn
 
-@cindex encrypt region
+@cindex encrypt a region
 @deffn Command epa-encrypt-region start end recipients sign signers
 Encrypt the current region between @var{start} and @var{end}.  It will
 let you select recipients.  If a prefix argument is given, it will
@@ -279,26 +274,26 @@ Cryptographic operations on regions
 @node Cryptographic operations on files
 @section Cryptographic Operations on Files
 @cindex cryptographic operations on files
-@cindex file operations
+@cindex file operations, cryptographic
 
-@cindex decrypt file
+@cindex decrypt a file
 @deffn Command epa-decrypt-file file &optional output
 Decrypt @var{file}.  If you do not specify the name @var{output} to
 use for the decrypted file, this function prompts for the value to use.
 @end deffn
 
-@cindex verify file
+@cindex verify a file
 @deffn Command epa-verify-file file
 Verify @var{file}.
 @end deffn
 
-@cindex sign file
+@cindex sign a file
 @deffn Command epa-sign-file file signers type
 Sign @var{file}.  If a prefix argument is given, it will let you
 select signing keys, and then a signature type.
 @end deffn
 
-@cindex encrypt file
+@cindex encrypt a file
 @deffn Command epa-encrypt-file file recipients
 Encrypt @var{file}.  It will let you select recipients.
 @end deffn
@@ -348,8 +343,7 @@ Dired integration
 @node Mail-mode integration
 @section Mail-Mode Integration
 @cindex mail-mode integration
-@cindex sending signed mails
-@cindex sending encrypted mails
+@cindex sending signed/encrypted mails
 
 EasyPG Assistant provides a minor mode @code{epa-mail-mode} to help
 user compose inline OpenPGP messages.  Inline OpenPGP is a traditional
@@ -407,7 +401,7 @@ Encrypting/decrypting gpg files
 @section Encrypting and Decrypting gpg Files
 @cindex encrypting gpg files
 @cindex decrypting gpg files
-@cindex gpg files
+@cindex gpg files, encrypting and decrypting
 @cindex automatic file encryption and decryption
 
 By default, every file whose name ends with @file{.gpg} will be
@@ -493,9 +487,8 @@ Encrypting/decrypting gpg files
 
 @node Querying a key server
 @section Querying a Key Server
-@cindex querying key server
-@cindex query key server
-@cindex key server
+@cindex query a key server
+@cindex key server, querying
 
 The @code{epa-search-keys} command can be used to query a
 @acronym{GPG} key server.  Emacs will then pop up a buffer that lists
@@ -510,9 +503,9 @@ Querying a key server
 
 @node GnuPG version compatibility
 @chapter GnuPG Version Compatibility
-@cindex gnupg version compatibility
-@cindex version compatibility
-@cindex compatibility
+@cindex GnuPG version compatibility
+@cindex version compatibility with GnuPG
+@cindex compatibility with GnuPG
 
 As of February 2016, there are three active branches of GnuPG: 2.1,
 2.0, and 1.4.  All those branches should work flawlessly with Emacs
@@ -547,8 +540,7 @@ Caching Passphrases
 @chapter Caching Passphrases
 @cindex caching passphrases
 @cindex entering passphrases
-@cindex passphrase cache
-@cindex passphrases
+@cindex passphrases, entering and caching
 
 Typing passphrases is a troublesome task if you frequently open and
 close the same file.  GnuPG and EasyPG Assistant provide mechanisms to
-- 
2.30.2

bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi

[Eli Zaretskii]

> Date: Sat, 1 Jul 2023 18:56:20 +0200
> Cc: 64154@debbugs.gnu.org
> From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
> 
> Thanks for the review, next version attached.

Will review later.

> > Likewise here.  You need to remember that typing "i compatibility"
> > in the Info reader will find the "gnupg version compatibility"
> > entry, because Info-index uses substring search in the indices.
> 
> ... I don't quite agree on that one: For example, I use completion on my
> index queries.  And at least with my configuration ("-Q" is different
> here, agreed) I won't find "gnupg version compatibility" when I type
> "comp TAB" and if there would be only
> 
>    @chapter GnuPG Version Compatibility
>    @cindex gnupg version compatibility

Using completion is not the only way of using the index: one can
simply type the word or phrase, and review all the hits, without
hitting TAB.  But yes, you need to consider completion as well, so
when you remove redundant index entries, you should remove those that
begin with words that are less likely to be used.

And this actually raises the main issue with writing good index
entries: you need to think about typical phrases that users will have
in mind when looking for the subject at hand.  E.g., is "gnupg version
compatibility" something that users will want to find?  Maybe changing
it to "compatibility of gnupg versions" would be better?

> Similar problems arise if anybody actually cares looking at the
> alphabetically ordered index, be it in an online reader or in print.
> (After all an index should be there for alphabetical lookup, shouldn't it?)

Not in the on-line manual, no.  Index entries in Info are intended to
be used without going to the Index node at all.

> Also here are some examples from the Elisp reference manual which I used
> as reference:

If you want to say that other manuals have index entries that can be
improved, you are preaching to the choir.  I improve existing index
entries almost every time I make any change in the manuals.  So don't
be surprised that you see in the manuals examples of what I consider
less-than-perfect indexing, and don't use that as justification to
copy those imperfect indexing techniques.

> Finally, even the Texinfo manual recommends (Index Entries(texinfo)):
> 
>    For example, one reader may think it obvious that the
>    two-letter names for indices should be listed under "Indices,
>    two-letter names", since "Indices" are the general concept.
>    But another reader may remember the specific concept of
>    two-letter names and search for the entry listed as "Two letter
>    names for indices".  A good index will have both entries and
>    will help both readers.

You indeed need to think about this, but I must say that their example
about "two letter names" is very far-fetched.  People who remember
that much will likely remember the index name itself and look for "cp
index" or somesuch.

> BTW, above chapter also has a note on capitalization of index entries,
> so I went for "GnuPG" and "EasyPG" in the index entries instead of all
> lower-casing them.

Please don't.  Capitalized index entries sort in locale-dependent
order, so the Index nodes look different depending on the locale where
the manual was produced, and in some cases this could land the reader
in a node other than the one you intended, if there are index entries
for "Foo something" and "foo some other".

> >> +@cindex insert key
>  >> +@deffn Command epa-insert-keys keys>
> > "@cindex insert keys" is better.
> 
> Agreed.  However, I'm not quite sure for what reason you proposed that,

The text and the name of the command use "keys", that's why.

> so I changed, for example
> 
>    @cindex decrypt region
> 
> to
> 
>    @cindex decrypt *a* region
> 
> and not to
> 
>    @cindex decrypt regions

I didn't comment on "decrypt region".

As for adding the "a" part, I think it's a mistake: index entries
don't need articles, and they get in the way of completion.

> Finally, I noticed that the index entries are not quite consistent 
> w.r.t. tense: Some use present tense, some present continuous.  I could 
> change that ...

There are no rules here, only common sense and the projected use by
the readers.

bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi

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

On 2023-07-01  19:19, Eli Zaretskii wrote:
>> Date: Sat, 1 Jul 2023 18:56:20 +0200 Cc: 64154@debbugs.gnu.org 
>> From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
>> 
>> Thanks for the review, next version attached.
> 
> Will review later.

Sigh.  Probably no need for it.  You have some good points, and after
reading them I understand that I need to go for a further round-trip.
So you might want to wait for that and review the combined patches.

>> ... I don't quite agree on that one: For example, I use completion 
>> on my index queries.  And at least with my configuration ("-Q" is 
>> different here, agreed) I won't find "gnupg version compatibility" 
>> when I type "comp TAB" and if there would be only
>> 
>> @chapter GnuPG Version Compatibility @cindex gnupg version 
>> compatibility
> 
> Using completion is not the only way of using the index: one can 
> simply type the word or phrase, and review all the hits, without 
> hitting TAB.  But yes, you need to consider completion as well, so 
> when you remove redundant index entries, you should remove those that
> begin with words that are less likely to be used.
> 
> And this actually raises the main issue with writing good index 
> entries: you need to think about typical phrases that users will have
> in mind when looking for the subject at hand.  E.g., is "gnupg 
> version compatibility" something that users will want to find?
> Maybe changing it to "compatibility of gnupg versions" would be
> better?

I actually (almost) had this one:

   @cindex GnuPG version compatibility
   @cindex version compatibility with GnuPG
   @cindex compatibility with GnuPG

so I hope we're closing in.

Not sure though: Are these three entries "too redundant" in your
opinion?  And if so, why would that hurt?

>> Similar problems arise if anybody actually cares looking at the 
>> alphabetically ordered index, be it in an online reader or in 
>> print. (After all an index should be there for alphabetical
>> lookup, shouldn't it?)
> 
> Not in the on-line manual, no.  Index entries in Info are intended to
> be used without going to the Index node at all.

What about those who use pdf or even print this stuff?

>> BTW, above chapter also has a note on capitalization of index 
>> entries, so I went for "GnuPG" and "EasyPG" in the index entries 
>> instead of all lower-casing them.
> 
> Please don't.  Capitalized index entries sort in locale-dependent 
> order, so the Index nodes look different depending on the locale 
> where the manual was produced, and in some cases this could land the 
> reader in a node other than the one you intended, if there are index 
> entries for "Foo something" and "foo some other".

OK, will undo that.

> As for adding the "a" part, I think it's a mistake: index entries 
> don't need articles, and they get in the way of completion.

Will undo that as well.

>> Finally, I noticed that the index entries are not quite consistent 
>> w.r.t. tense: Some use present tense, some present continuous.  I 
>> could change that ...
> 
> There are no rules here, only common sense and the projected use by 
> the readers.

Does this "no rules" relate to only to my last statement or to index
entries in general?  Because in general you seem to have quite a bunch
of rules, and well-founded ones, and if had known these before we could
have saved a round-trip or two.  But I don't even dare to propose 
changing the Texinfo manual ...

bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi

[Eli Zaretskii]

> Date: Sat, 1 Jul 2023 19:56:08 +0200
> Cc: 64154@debbugs.gnu.org
> From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
> 
>    @cindex GnuPG version compatibility
>    @cindex version compatibility with GnuPG
>    @cindex compatibility with GnuPG
> 
> so I hope we're closing in.
> 
> Not sure though: Are these three entries "too redundant" in your
> opinion?  And if so, why would that hurt?

They are not redundant, since they all start differently.  But I would
suggest to consider the first one for removal.

> >> Similar problems arise if anybody actually cares looking at the 
> >> alphabetically ordered index, be it in an online reader or in 
> >> print. (After all an index should be there for alphabetical
> >> lookup, shouldn't it?)
> > 
> > Not in the on-line manual, no.  Index entries in Info are intended to
> > be used without going to the Index node at all.
> 
> What about those who use pdf or even print this stuff?

The alphabetic order of the index in the printed versions exists to
help finding the index entries.  People still first think about what
they want to find, and only then look it up.

> >> Finally, I noticed that the index entries are not quite consistent 
> >> w.r.t. tense: Some use present tense, some present continuous.  I 
> >> could change that ...
> > 
> > There are no rules here, only common sense and the projected use by 
> > the readers.
> 
> Does this "no rules" relate to only to my last statement or to index
> entries in general?

The former.

> Because in general you seem to have quite a bunch of rules, and
> well-founded ones, and if had known these before we could have saved
> a round-trip or two.  But I don't even dare to propose changing the
> Texinfo manual ...

The Texinfo manual doesn't need to be changed.  It's a very good
manual.  As for "no rules", the most important rule for index entries
is that they should fit what people have in mind when they look for
the subject.  All the rest are corollaries and gray hair gained by
experience.

bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi

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

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

On 2023-07-01  20:49, Eli Zaretskii wrote:

Attached a third patch - please review 2nd and 3rd combined against 1st.

>>     @cindex GnuPG version compatibility
>>     @cindex version compatibility with GnuPG
>>     @cindex compatibility with GnuPG
> 
> They are not redundant, since they all start differently.  But I would
> suggest to consider the first one for removal.

Why, then?  I can imagine using that as index search, for example if I
remember that the section is named like that.  Plus it does not seem to
break completion.

> The Texinfo manual doesn't need to be changed.  It's a very good
> manual.  [...]

At least w.r.t. to capitalization you both seem to fundamentally
disagree (quotes from "Index Entries(texinfo)"):

   [...] capitalizing only proper
   names and acronyms that always call for uppercase letters.
   This is the case convention we use in most GNU manuals'
   indices.

OTOH here you completely agree:

   Like typesetting, the construction of an index is a skilled
   art, the subtleties of which may not be appreciated until you
   need to do it yourself.

[-- Attachment #2: 0003-Brush-up-index-entries-after-review.patch --]
[-- Type: text/x-patch, Size: 4925 bytes --]

From 8335d96553e2d29df0bffceaef9022c38beab1ff Mon Sep 17 00:00:00 2001
From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
Date: Sat, 1 Jul 2023 21:53:31 +0200
Subject: [PATCH] Brush up index entries after review

* doc/misc/epa.texi (Top, Overview, Key management)
(Cryptographic operations on regions, Cryptographic operations on files)
(Encrypting/decrypting gpg files, Querying a key server): Brush up
index entries after review.  (Bug#64154)
---
 doc/misc/epa.texi | 38 +++++++++++++++++++-------------------
 1 file changed, 19 insertions(+), 19 deletions(-)

diff --git a/doc/misc/epa.texi b/doc/misc/epa.texi
index 4b998939ef5..edfe37de816 100644
--- a/doc/misc/epa.texi
+++ b/doc/misc/epa.texi
@@ -44,9 +44,9 @@
 
 @node Top
 @top EasyPG Assistant User's Manual
-@cindex EasyPG Assistant
-@cindex GNU Privacy Guard
-@cindex GnuPG
+@cindex easypg assistant
+@cindex gnu privacy guard
+@cindex gnupg
 
 EasyPG Assistant is an Emacs user interface to GNU Privacy Guard
 (GnuPG, @pxref{Top, , Top, gnupg, Using the GNU Privacy Guard}).
@@ -81,7 +81,7 @@ Top
 
 @node Overview
 @chapter Overview
-@cindex features of EasyPG Assistant
+@cindex features of easypg assistant
 
 EasyPG Assistant provides the following features.
 
@@ -96,7 +96,7 @@ Overview
 
 @node Quick start
 @chapter Quick Start
-@cindex introduction to EasyPG Assistant
+@cindex introduction to easypg assistant
 
 EasyPG Assistant commands are prefixed by @samp{epa-}.  For example,
 
@@ -134,7 +134,7 @@ Key management
 @cindex key management
 
 @cindex key ring, browsing
-@cindex browse the key ring
+@cindex browse key ring
 Probably the first step of using EasyPG Assistant is to browse your
 keyring.  @kbd{M-x epa-list-keys} is corresponding to @samp{gpg
 --list-keys} from the command line.
@@ -223,9 +223,9 @@ Key management
 @node Cryptographic operations on regions
 @section Cryptographic Operations on Regions
 @cindex cryptographic operations on regions
-@cindex region operations
+@cindex region operations, cryptographic
 
-@cindex decrypt a region
+@cindex decrypt region
 @deffn Command epa-decrypt-region start end
 Decrypt the current region between @var{start} and @var{end}.  It
 replaces the region with the decrypted text.
@@ -239,7 +239,7 @@ Cryptographic operations on regions
 command does not alter the original text around armors.
 @end deffn
 
-@cindex verify a region
+@cindex verify region
 @deffn Command epa-verify-region start end
 Verify the current region between @var{start} and @var{end}.  It sends
 the verification result to the minibuffer or a popup window.  It
@@ -255,7 +255,7 @@ Cryptographic operations on regions
 not alter the original text around OpenPGP cleartext blocks.
 @end deffn
 
-@cindex sign a region
+@cindex sign region
 @deffn Command epa-sign-region start end signers type
 Sign the current region between @var{start} and @var{end}.  By
 default, it creates a cleartext signature.  If a prefix argument is
@@ -263,7 +263,7 @@ Cryptographic operations on regions
 type.
 @end deffn
 
-@cindex encrypt a region
+@cindex encrypt region
 @deffn Command epa-encrypt-region start end recipients sign signers
 Encrypt the current region between @var{start} and @var{end}.  It will
 let you select recipients.  If a prefix argument is given, it will
@@ -276,24 +276,24 @@ Cryptographic operations on files
 @cindex cryptographic operations on files
 @cindex file operations, cryptographic
 
-@cindex decrypt a file
+@cindex decrypt file
 @deffn Command epa-decrypt-file file &optional output
 Decrypt @var{file}.  If you do not specify the name @var{output} to
 use for the decrypted file, this function prompts for the value to use.
 @end deffn
 
-@cindex verify a file
+@cindex verify file
 @deffn Command epa-verify-file file
 Verify @var{file}.
 @end deffn
 
-@cindex sign a file
+@cindex sign file
 @deffn Command epa-sign-file file signers type
 Sign @var{file}.  If a prefix argument is given, it will let you
 select signing keys, and then a signature type.
 @end deffn
 
-@cindex encrypt a file
+@cindex encrypt file
 @deffn Command epa-encrypt-file file recipients
 Encrypt @var{file}.  It will let you select recipients.
 @end deffn
@@ -487,7 +487,7 @@ Encrypting/decrypting gpg files
 
 @node Querying a key server
 @section Querying a Key Server
-@cindex query a key server
+@cindex query key server
 @cindex key server, querying
 
 The @code{epa-search-keys} command can be used to query a
@@ -503,9 +503,9 @@ Querying a key server
 
 @node GnuPG version compatibility
 @chapter GnuPG Version Compatibility
-@cindex GnuPG version compatibility
-@cindex version compatibility with GnuPG
-@cindex compatibility with GnuPG
+@cindex gnupg version compatibility
+@cindex version compatibility with gnupg
+@cindex compatibility with gnupg
 
 As of February 2016, there are three active branches of GnuPG: 2.1,
 2.0, and 1.4.  All those branches should work flawlessly with Emacs
-- 
2.30.2

bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi

[Eli Zaretskii]

> Date: Sat, 1 Jul 2023 22:20:12 +0200
> Cc: 64154@debbugs.gnu.org
> From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
> 
> >>     @cindex GnuPG version compatibility
> >>     @cindex version compatibility with GnuPG
> >>     @cindex compatibility with GnuPG
> > 
> > They are not redundant, since they all start differently.  But I would
> > suggest to consider the first one for removal.
> 
> Why, then?

Because people are very unlikely to think about "GnuPG version
compatibility".  They are likely to think about "version
compatibility" and perhaps just "compatibility".  Just put yourself
into the shoes of such a reader, and ask yourself what would you type
at Info-index's prompt.

> I can imagine using that as index search, for example if I remember
> that the section is named like that.  Plus it does not seem to break
> completion.

If you remember the name of the section, you can usually use 'g',
since node names are usually very similar to section names.

> > The Texinfo manual doesn't need to be changed.  It's a very good
> > manual.  [...]
> 
> At least w.r.t. to capitalization you both seem to fundamentally
> disagree (quotes from "Index Entries(texinfo)"):
> 
>    [...] capitalizing only proper
>    names and acronyms that always call for uppercase letters.
>    This is the case convention we use in most GNU manuals'
>    indices.

My personal rule is to use capital letters in index entries only when
absolutely necessary.  It is not necessary with "gpg" or "gnupg".  The
above citation says something similar.

> Attached a third patch - please review 2nd and 3rd combined against 1st.

Does it mean the patch you sent is just part of the changes?

bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi

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

On 2023-07-02  06:59, Eli Zaretskii wrote:

> Because people are very unlikely to think about "GnuPG version 
> compatibility".  They are likely to think about "version 
> compatibility" and perhaps just "compatibility".  Just put yourself 
> into the shoes of such a reader, and ask yourself what would you
> type at Info-index's prompt.

But after all, I *am* such a reader.  And I would type that, because "i"
is my main entry point to Info manuals, not "g".

My question here really is: Why would it be bad to have that additional
index entry?  It does not break completion, it is not overly generic, it
is just ... there, ready for some less likely reader to search for it.

(Spoiler: *That* one entry is still in, even in my latest patch.  I
understood your comment:

>>> They are not redundant, since they all start differently.  But I 
>>> would suggest to consider the first one for removal.

to mean that removal is recommended but optional.  Please let me know if
you meant otherwise.)

>> At least w.r.t. to capitalization you both seem to fundamentally 
>> disagree (quotes from "Index Entries(texinfo)"):
>> 
>> [...] capitalizing only proper names and acronyms that always call
>> for uppercase letters. This is the case convention we use in most
>> GNU manuals' indices.
> 
> My personal rule is to use capital letters in index entries only
> when absolutely necessary.  It is not necessary with "gpg" or
> "gnupg".  The above citation says something similar.

I would have considered "EasyPG Assistant" a proper name and the "GNU"
in "GNU Privacy Guard" an acronym, but anyway ...

>> Attached a third patch - please review 2nd and 3rd combined against
>> 1st.
> 
> Does it mean the patch you sent is just part of the changes?

Yes, it is.  It undoes some of the changes of the previous patch.

bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi

[Eli Zaretskii]

> Date: Sun, 2 Jul 2023 09:13:25 +0200
> Cc: 64154@debbugs.gnu.org
> From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
> 
> On 2023-07-02  06:59, Eli Zaretskii wrote:
> 
> > Because people are very unlikely to think about "GnuPG version 
> > compatibility".  They are likely to think about "version 
> > compatibility" and perhaps just "compatibility".  Just put yourself 
> > into the shoes of such a reader, and ask yourself what would you
> > type at Info-index's prompt.
> 
> But after all, I *am* such a reader.  And I would type that, because "i"
> is my main entry point to Info manuals, not "g".

Then go for it!

> My question here really is: Why would it be bad to have that additional
> index entry?

I said "I'd consider that for removal", that's all.  If you considered
it and decided to leave it, fine.  It's a judgment call.

> >> Attached a third patch - please review 2nd and 3rd combined against
> >> 1st.
> > 
> > Does it mean the patch you sent is just part of the changes?
> 
> Yes, it is.  It undoes some of the changes of the previous patch.

Can you send a single patch with all the changes, please?

bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi

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

On 2023-07-02  10:18, Eli Zaretskii wrote:

> Can you send a single patch with all the changes, please?

Ok, next general question, probably I have misunderstood your previous 
comment on that.  git lingo is still somewhat new to me...

Suppose I provide a patch P1 on emacs-29 and you review P1.  How should 
I provide the changes CH resulting from that review?  With a patch P2 
like this (A):

   emacs-29 -> P1 -> P2

Or with a patch P1' merging P1 and P2 like this (B):

   emacs-29 -> P1'

Or does it depend on the changes CH and you decide case-by-case (C)?

bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi

[Eli Zaretskii]

> Date: Sun, 2 Jul 2023 13:54:16 +0200
> Cc: 64154@debbugs.gnu.org
> From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
> 
> On 2023-07-02  10:18, Eli Zaretskii wrote:
> 
> > Can you send a single patch with all the changes, please?
> 
> Ok, next general question, probably I have misunderstood your previous 
> comment on that.  git lingo is still somewhat new to me...
> 
> Suppose I provide a patch P1 on emacs-29 and you review P1.  How should 
> I provide the changes CH resulting from that review?  With a patch P2 
> like this (A):
> 
>    emacs-29 -> P1 -> P2
> 
> Or with a patch P1' merging P1 and P2 like this (B):
> 
>    emacs-29 -> P1'
> 
> Or does it depend on the changes CH and you decide case-by-case (C)?

I usually prefer to see a single patch relative to the current Git,
even in subsequent reviews.

bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi

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

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

On 2023-07-02  10:18, Eli Zaretskii wrote:

> Can you send a single patch with all the changes, please?

Here you go.

Thanks

[-- Attachment #2: 0001-Add-concept-index-title-case-structure-titles.patch --]
[-- Type: text/x-patch, Size: 8848 bytes --]

From aca7182f57d3ef23c1a422c9a171de672b1a036c Mon Sep 17 00:00:00 2001
From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
Date: Sun, 2 Jul 2023 13:39:48 +0200
Subject: [PATCH] Add concept index, title-case structure titles

* doc/misc/epa.texi (Top, Overview, Commands, Key management)
(Cryptographic operations on regions, Cryptographic operations on files)
(Dired integration, Mail-mode integration)
(Encrypting/decrypting gpg files, Querying a key server)
(GnuPG version compatibility, Caching Passphrases)
(GNU Free Documentation License): Add concept index, title-case
structure titles.  (Bug#64154)
---
 doc/misc/epa.texi | 77 ++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 66 insertions(+), 11 deletions(-)

diff --git a/doc/misc/epa.texi b/doc/misc/epa.texi
index 6f63a3d7ba0..edfe37de816 100644
--- a/doc/misc/epa.texi
+++ b/doc/misc/epa.texi
@@ -43,7 +43,10 @@
 @contents
 
 @node Top
-@top EasyPG Assistant user's manual
+@top EasyPG Assistant User's Manual
+@cindex easypg assistant
+@cindex gnu privacy guard
+@cindex gnupg
 
 EasyPG Assistant is an Emacs user interface to GNU Privacy Guard
 (GnuPG, @pxref{Top, , Top, gnupg, Using the GNU Privacy Guard}).
@@ -56,6 +59,12 @@ Top
 @insertcopying
 @end ifnottex
 
+@c Unfortunately the node names of this manual are not very consistent
+@c w.r.t. their case.  However, case is significant in node names, so
+@c we probably better should not change these to not break any
+@c external references.  Things are more relaxed for structure titles,
+@c so we consistently updated them to title-case.
+
 @menu
 * Overview::
 * Quick start::
@@ -64,6 +73,7 @@ Top
 * Caching Passphrases::
 * Bug Reports::
 * GNU Free Documentation License::  The license for this documentation.
+* Concept Index::
 * Key Index::
 * Function Index::
 * Variable Index::
@@ -71,6 +81,7 @@ Top
 
 @node Overview
 @chapter Overview
+@cindex features of easypg assistant
 
 EasyPG Assistant provides the following features.
 
@@ -84,7 +95,8 @@ Overview
 @end itemize
 
 @node Quick start
-@chapter Quick start
+@chapter Quick Start
+@cindex introduction to easypg assistant
 
 EasyPG Assistant commands are prefixed by @samp{epa-}.  For example,
 
@@ -118,7 +130,11 @@ Commands
 @end menu
 
 @node Key management
-@section Key management
+@section Key Management
+@cindex key management
+
+@cindex key ring, browsing
+@cindex browse key ring
 Probably the first step of using EasyPG Assistant is to browse your
 keyring.  @kbd{M-x epa-list-keys} is corresponding to @samp{gpg
 --list-keys} from the command line.
@@ -157,6 +173,7 @@ Key management
         Fingerprint: 9003 D76B 73B7 4A8A E588  10AF 4447 461B 2A9B EA2D
 @end example
 
+@cindex private key ring, browsing
 @noindent
 To browse your private keyring, use @kbd{M-x epa-list-secret-keys}.
 
@@ -172,12 +189,14 @@ Key management
 Below are other commands related to key management.  Some of them take
 a file as input/output, and others take the current region.
 
+@cindex insert keys
 @deffn Command epa-insert-keys keys
 Insert selected @var{keys} after the point.  It will let you select
 keys before insertion.  By default, it will encode keys in the OpenPGP
 armor format.
 @end deffn
 
+@cindex import keys
 @deffn Command epa-import-keys file
 Import keys from @var{file} to your keyring.
 @end deffn
@@ -195,14 +214,18 @@ Key management
 applies @code{epa-import-keys-region} to each of them.
 @end deffn
 
+@cindex delete keys
 @deffn Command epa-delete-keys allow-secret
 Delete selected keys.  If @var{allow-secret} is non-@code{nil}, it
 also delete the secret keys.
 @end deffn
 
 @node Cryptographic operations on regions
-@section Cryptographic operations on regions
+@section Cryptographic Operations on Regions
+@cindex cryptographic operations on regions
+@cindex region operations, cryptographic
 
+@cindex decrypt region
 @deffn Command epa-decrypt-region start end
 Decrypt the current region between @var{start} and @var{end}.  It
 replaces the region with the decrypted text.
@@ -216,6 +239,7 @@ Cryptographic operations on regions
 command does not alter the original text around armors.
 @end deffn
 
+@cindex verify region
 @deffn Command epa-verify-region start end
 Verify the current region between @var{start} and @var{end}.  It sends
 the verification result to the minibuffer or a popup window.  It
@@ -231,6 +255,7 @@ Cryptographic operations on regions
 not alter the original text around OpenPGP cleartext blocks.
 @end deffn
 
+@cindex sign region
 @deffn Command epa-sign-region start end signers type
 Sign the current region between @var{start} and @var{end}.  By
 default, it creates a cleartext signature.  If a prefix argument is
@@ -238,6 +263,7 @@ Cryptographic operations on regions
 type.
 @end deffn
 
+@cindex encrypt region
 @deffn Command epa-encrypt-region start end recipients sign signers
 Encrypt the current region between @var{start} and @var{end}.  It will
 let you select recipients.  If a prefix argument is given, it will
@@ -246,28 +272,37 @@ Cryptographic operations on regions
 @end deffn
 
 @node Cryptographic operations on files
-@section Cryptographic operations on files
+@section Cryptographic Operations on Files
+@cindex cryptographic operations on files
+@cindex file operations, cryptographic
 
+@cindex decrypt file
 @deffn Command epa-decrypt-file file &optional output
 Decrypt @var{file}.  If you do not specify the name @var{output} to
 use for the decrypted file, this function prompts for the value to use.
 @end deffn
 
+@cindex verify file
 @deffn Command epa-verify-file file
 Verify @var{file}.
 @end deffn
 
+@cindex sign file
 @deffn Command epa-sign-file file signers type
 Sign @var{file}.  If a prefix argument is given, it will let you
 select signing keys, and then a signature type.
 @end deffn
 
+@cindex encrypt file
 @deffn Command epa-encrypt-file file recipients
 Encrypt @var{file}.  It will let you select recipients.
 @end deffn
 
 @node Dired integration
-@section Dired integration
+@section Dired Integration
+@cindex dired integration
+@cindex directory operations
+@cindex multiple file operations
 
 EasyPG Assistant extends Dired Mode for GNU Emacs to allow users to
 easily do cryptographic operations on files.  For example,
@@ -306,7 +341,9 @@ Dired integration
 @end table
 
 @node Mail-mode integration
-@section Mail-mode integration
+@section Mail-Mode Integration
+@cindex mail-mode integration
+@cindex sending signed/encrypted mails
 
 EasyPG Assistant provides a minor mode @code{epa-mail-mode} to help
 user compose inline OpenPGP messages.  Inline OpenPGP is a traditional
@@ -361,7 +398,12 @@ Mail-mode integration
 @end table
 
 @node Encrypting/decrypting gpg files
-@section Encrypting/decrypting gpg files
+@section Encrypting and Decrypting gpg Files
+@cindex encrypting gpg files
+@cindex decrypting gpg files
+@cindex gpg files, encrypting and decrypting
+@cindex automatic file encryption and decryption
+
 By default, every file whose name ends with @file{.gpg} will be
 treated as encrypted.  That is, when you open such a file, the
 decrypted text is inserted in the buffer rather than encrypted one.
@@ -444,7 +486,9 @@ Encrypting/decrypting gpg files
 @end defvar
 
 @node Querying a key server
-@section Querying a key server
+@section Querying a Key Server
+@cindex query key server
+@cindex key server, querying
 
 The @code{epa-search-keys} command can be used to query a
 @acronym{GPG} key server.  Emacs will then pop up a buffer that lists
@@ -457,9 +501,11 @@ Querying a key server
 
 The @code{epa-keyserver} variable says which server to query.
 
-
 @node GnuPG version compatibility
-@chapter GnuPG version compatibility
+@chapter GnuPG Version Compatibility
+@cindex gnupg version compatibility
+@cindex version compatibility with gnupg
+@cindex compatibility with gnupg
 
 As of February 2016, there are three active branches of GnuPG: 2.1,
 2.0, and 1.4.  All those branches should work flawlessly with Emacs
@@ -492,6 +538,9 @@ GnuPG version compatibility
 
 @node Caching Passphrases
 @chapter Caching Passphrases
+@cindex caching passphrases
+@cindex entering passphrases
+@cindex passphrases, entering and caching
 
 Typing passphrases is a troublesome task if you frequently open and
 close the same file.  GnuPG and EasyPG Assistant provide mechanisms to
@@ -532,6 +581,8 @@ Caching Passphrases
 
 @node Bug Reports
 @chapter Bug Reports
+@cindex bug reports
+@cindex reporting bugs
 
 Bugs and problems with EasyPG Assistant are actively worked on by the
 Emacs development team.  Feature requests and suggestions are also
@@ -556,6 +607,10 @@ GNU Free Documentation License
 @appendix GNU Free Documentation License
 @include doclicense.texi
 
+@node Concept Index
+@unnumbered Concept Index
+@printindex cp
+
 @node Key Index
 @unnumbered Key Index
 @printindex ky
-- 
2.30.2

bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi

[Eli Zaretskii]

> Date: Sun, 2 Jul 2023 13:55:08 +0200
> Cc: 64154@debbugs.gnu.org
> From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
> 
> > Can you send a single patch with all the changes, please?
> 
> Here you go.

Thanks, this LGTM.

bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi

[Eli Zaretskii]

> Date: Fri, 30 Jun 2023 21:13:40 +0200
> Cc: 64154@debbugs.gnu.org
> From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
> 
> On 2023-06-30  07:54, Eli Zaretskii wrote:
> 
> > Yes, please.  A manual that lacks Concept Index is not a good manual,
> > IMO.  In fact, Concept Index should be the very first index in a
> > manual; there are some good manuals which have only that and nothing
> > else.
> 
> Another such possible systematic update I could do while touching 
> things: Consistently title-casing node names and/or chapter/section 
> titles.  OK or not OK?  I'm not sure about external references if case 
> changes.

Chapters and sections should be capitalized according to the rules of
English.  Node names I'd leave a lone: there's no capitalization
convention about them.

bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Problem here being that epa.texi has no concept index yet.  Should I
  > create one from the existing chapters/sections/subsections in a separate
  > patch?

It would be good to make a concept index, but please index all the
concepts mentioned -- not just the ones that are names of secxtions.

If you look at @cindex commands in the Emacs manual, which has a very
thorough concept index, you'll see that there are @cindex commands for
many concepts which do not appear in section titles.  This is the way
to do a complete job.  Please do a complete job for EPA too!

If you search for @cindex in the Emacs manual sources, you can see
this quickly.  Looking through 20% of the manual should be enough to
give you the picture.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi

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

On 2023-07-02  04:15, Richard Stallman wrote:

>> Problem here being that epa.texi has no concept index yet.  Should I
>> create one from the existing chapters/sections/subsections in a separate
>> patch?
> 
> It would be good to make a concept index, but please index all the
> concepts mentioned -- not just the ones that are names of secxtions.

I was initially hoping for the better-than-nothing half of Dick's quote 
from the Texinfo manual:

   Documentation is like sex: when it is good, it is very, very good;
   and when it is bad, it is better than nothing.  --Dick Brandon

But Eli is already trying hard to direct me otherwise, thanks.

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

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

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

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.

On 2023-06-17  09:44, Eli Zaretskii wrote:

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

Understood.  Actually, I copied the habit of the original authors there.
I fixed my own inappropriate @xrefs plus theirs.

>> +@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?  Same question for @pxref?

>> +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.  I use now "...
described further below in this section" to clarify that.

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

Done that.

Finally, I noticed that node "GnuPG and EasyPG Assistant
Configuration(auth)" duplicates some of the information in section
"Caching Passphrases(epa)", which means that these will be out of sync
as soon as my changes have landed.  WDYT about that?

[-- Attachment #2: 0002-Add-basic-usage-information-and-fix-references.patch --]
[-- Type: text/x-patch, Size: 13886 bytes --]

From a789918509e5292b8e883012a1b4a03d740506a9 Mon Sep 17 00:00:00 2001
From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
Date: Sat, 8 Jul 2023 22:19:45 +0200
Subject: [PATCH] Add basic usage information and fix references

* doc/misc/epa.texi (Top): Add menu entry for new node GnuPG Pinentry.
(Quick Start): Add information on and reference to basic GnuPG
configuration.
(Encrypting/decrypting gpg files): Add usage information.
(GnuPG version compatibility): Update version information.  Change
footnote referring to loopback pinentry to reference to new node GnuPG
pinentry.
(GnuPG Pinentry): Add new node.
(Caching Passphrases): Describe mandatory gpg-agent usage for GnuPG
2.0 and later.
(Overview, Encrypting/decrypting gpg files, Caching Passphrases)
(Bug Reports): Fix references.  (Bug#64154)
---
 doc/misc/epa.texi | 195 +++++++++++++++++++++++++++++++++++++---------
 1 file changed, 160 insertions(+), 35 deletions(-)

diff --git a/doc/misc/epa.texi b/doc/misc/epa.texi
index edfe37de816..94e7447c927 100644
--- a/doc/misc/epa.texi
+++ b/doc/misc/epa.texi
@@ -70,6 +70,7 @@ Top
 * Quick start::
 * Commands::
 * GnuPG version compatibility::
+* GnuPG Pinentry::
 * Caching Passphrases::
 * Bug Reports::
 * GNU Free Documentation License::  The license for this documentation.
@@ -83,7 +84,8 @@ Overview
 @chapter Overview
 @cindex features of easypg assistant
 
-EasyPG Assistant provides the following features.
+EasyPG Assistant is an Emacs frontend application to @acronym{GnuPG,
+GNU Privacy Guard} that provides the following features:
 
 @itemize @bullet
 @item Key management.
@@ -97,6 +99,22 @@ Overview
 @node Quick start
 @chapter Quick Start
 @cindex introduction to easypg assistant
+@cindex gnupg documentation
+@cindex documentation on gnupg
+@cindex configuration of gnupg
+@cindex introduction to gnupg
+
+You can use EasyPG Assistant without any Emacs or GnuPG configuration
+whatsoever, for example to encrypt and decrypt files automatically
+with symmetric encryption, see @ref{Encrypting/decrypting gpg files}.
+However, to use the full set of EasyPG Assistant's functions you
+should have at least some minimum GnuPG configuration in place.
+
+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.
 
 EasyPG Assistant commands are prefixed by @samp{epa-}.  For example,
 
@@ -410,6 +428,42 @@ Encrypting/decrypting gpg files
 Similarly, when you save the buffer to a @file{foo.gpg} file,
 encrypted data is written.
 
+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
+@file{*Keys*} where you can select recipients for encryption.
+@xref{Key management}, for a description of the format of that buffer.
+You can streamline this recipient selection step by customizing
+variables @code{epa-file-encrypt-to} and @code{epa-file-select-keys}
+described further below in this section.
+
+@cindex symmetric encryption, passphrase entry for
+If you do not select any recipient during this step, EasyPG Assistant
+uses symmetric encryption.  As a consequence, you have to enter the
+passphrase twice for every buffer save and every so often for file
+reads, since the gpg-agent caches your passphrase for file reads at
+least for some time, but not for buffer saves.
+
+@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.  Since GnuPG performs encryption with your
+public key, it does not prompt for a passphrase for the buffer save,
+but it will prompt for your passphrase for file reads every now and
+then, depending on the gpg-agent cache configuration.
+
+@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}.  If you want to be sure not to leave
+any plain-text traces, use an encrypted file systems at least for that
+directory.
+
 The file name pattern for encrypted files can be controlled by
 @code{epa-file-name-regexp}.
 
@@ -447,9 +501,9 @@ Encrypting/decrypting gpg files
 @end defvar
 
 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
 
 For example, if you want an Elisp file to be encrypted with a
@@ -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.  Instead, consider using the gpg-agent, which in
+many cases can do the same job, and does it in a safer way.
+@xref{Caching Passphrases}, for more information.
 @end defvar
 
 @defvar epa-file-inhibit-auto-save
@@ -507,10 +566,17 @@ GnuPG version compatibility
 @cindex version compatibility with gnupg
 @cindex compatibility with gnupg
 
-As of February 2016, there are three active branches of GnuPG: 2.1,
-2.0, 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.
+As of June 2023, there are three active branches of GnuPG: 2.4, 2.2,
+and 1.4.  GnuPG versions 2.4.1 and later suffer from
+@uref{https://dev.gnupg.org/T6481, GnuPG bug T6481} and are hardly
+usable with Emacs.  There is a patch for that bug available at least
+for GnuPG version 2.4.1, which your operating system or distribution
+might provide already.  GnuPG 1.4 is considered a legacy version.
+
+Besides that, all of those branches mentioned above should work
+flawlessly with Emacs with basic use-cases.  They have, however, some
+incompatible characteristics, which might be visible when used from
+Emacs.
 
 @itemize
 @item
@@ -526,16 +592,77 @@ GnuPG version compatibility
 
 @item
 GnuPG 2.1 (2.1.5 or later) has a mechanism to direct the Pinentry
-password prompt to the Emacs minibuffer@footnote{To enable this
-feature, add @samp{allow-emacs-pinentry} to
-@file{~/.gnupg/gpg-agent.conf} and let gpg-agent reload the
-configuration, with: @samp{gpgconf --reload gpg-agent}}, which would
-be useful when you use Emacs remotely or from a text-only terminal.
-That feature is not available in other versions, and more
-specifically, with 2.0 (as of 2.0.29), there is no way to avoid the
-graphical prompt.
+password prompt to the Emacs minibuffer.  @xref{GnuPG Pinentry}.
 @end itemize
 
+@node GnuPG Pinentry
+@chapter GnuPG Pinentry
+@cindex gnupg pinentry
+@cindex pinentry provided by gnupg
+
+An important component of the GnuPG suite is the Pinentry, which
+allows for secure entry of passphrases requested by GnuPG.  GnuPG
+delivers various different programs as Pinentry, ranging from bland
+TTY-only @samp{pinentry-tty} to fancy graphical dialogs for various
+desktop environments, like @samp{pinentry-gnome3}.  Your operating
+system usually determines which of these is used by default.
+
+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 see @ref{Caching Passphrases}.
+
+@cindex pinentry, emacs as
+With some configuration Emacs can also play the role of a Pinentry.
+The most natural choice, available with GnuPG 2.1.5 and later, is to
+use Emacs itself as Pinentry for requests that are triggered by Emacs.
+For example, if you open a file whose name ends with @file{.gpg} using
+automatic decryption, you most likely also want to enter the
+passphrase for that request in Emacs.
+
+@cindex loopback pinentry
+This so called loopback Pinentry has the added benefit that it works
+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
+
+There are other options available to use Emacs as Pinentry, you might
+come across a Pinentry called @code{pinentry-emacs} or gpg-agent
+option @code{allow-emacs-pinentry}.  However, these are considered
+insecure or semi-obsolete and might not be supported by your operating
+system or distribution.  For example, Debian GNU/Linux supports only
+the loopback Pinentry described above.
+
+@c In case somebody requests these:
+@c
+@c Use Emacs for all GnuPG requests:
+@c
+@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
+@c passphrase requests should then result in a minibuffer prompt in
+@c the running Emacs.  If Emacs or the Emacs Pinentry service are not
+@c running, passphrase requests fail.
+@c
+@c Use Emacs for all GnuPG requests with other Pinentry as fallback:
+@c
+@c Ensure the other Pinentry supports Emacs prompt.  pinentry-curses
+@c does, for example.  Configure option allow-emacs-pinentry in
+@c gpg-agent.conf.  Set environment variable INSIDE_EMACS for the
+@c calling process.  Install package pinentry.el.  Now if Emacs is
+@c running and M-x pinentry-start has been executed, all GnuPG
+@c passphrase requests should result in a minibuffer prompt in the
+@c running Emacs.  If Emacs or the Emacs Pinentry service are not
+@c running, GnuPG uses the other Pinentry instead.
+
 @node Caching Passphrases
 @chapter Caching Passphrases
 @cindex caching passphrases
@@ -545,15 +672,15 @@ Caching Passphrases
 Typing passphrases is a troublesome task if you frequently open and
 close the same file.  GnuPG and EasyPG Assistant provide mechanisms to
 remember your passphrases for a limited time.  Using these, you only
-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 (symmetric or public key),
-and whether or not you want to use gpg-agent.  Here are some
-questions:
+need to re-enter the passphrase occasionally.  However, the
+configuration is a bit confusing since it depends on your GnuPG
+installation (@pxref{GnuPG version compatibility}), encryption method
+(symmetric or public key), and whether or not you want to use
+gpg-agent.  As an additional constraint, use of the gpg-agent is
+mandatory for GnuPG 2.0 and later.  Here are some questions:
 
 @enumerate
-@item Do you use GnuPG version 2.1 or 2.0 instead of GnuPG version 1.4?
+@item Do you use GnuPG version 2.0 or later instead of GnuPG version 1.4?
 @item Do you use symmetric encryption rather than public key encryption?
 @item Do you want to use gpg-agent?
 @end enumerate
@@ -562,18 +689,16 @@ Caching Passphrases
 
 @multitable {111} {222} {333} {configuration configuration configuration}
 @item @b{1} @tab @b{2} @tab @b{3} @tab Configuration
-@item Yes @tab Yes @tab Yes @tab Set up gpg-agent.
-@item Yes @tab Yes @tab No @tab You can't, without gpg-agent.
-@item Yes @tab No @tab Yes @tab Set up gpg-agent.
-@item Yes @tab No @tab No @tab You can't, without gpg-agent.
-@item No @tab Yes @tab Yes @tab Set up elisp passphrase cache.
-@item No @tab Yes @tab No @tab Set up elisp passphrase cache.
-@item No @tab No @tab Yes @tab Set up gpg-agent.
-@item No @tab No @tab No @tab You can't, without gpg-agent.
+@item Yes   @tab Yes   @tab Must  @tab Set up gpg-agent.
+@item Yes   @tab No    @tab Must  @tab Set up gpg-agent.
+@item No    @tab Yes   @tab Yes   @tab Set up elisp passphrase cache.
+@item No    @tab Yes   @tab No    @tab Set up elisp passphrase cache.
+@item No    @tab No    @tab Yes   @tab Set up gpg-agent.
+@item No    @tab No    @tab No    @tab You can't, without gpg-agent.
 @end multitable
 
-To set up gpg-agent, follow the instruction in GnuPG manual.
-@pxref{Invoking GPG-AGENT, , Invoking GPG-AGENT, gnupg}.
+To set up gpg-agent, follow the instruction in @ref{Invoking
+GPG-AGENT, , , gnupg, Using the GNU Privacy Guard}.
 
 To set up elisp passphrase cache, set
 @code{epa-file-cache-passphrase-for-symmetric-encryption}.
@@ -586,8 +711,8 @@ Bug Reports
 
 Bugs and problems with EasyPG Assistant are actively worked on by the
 Emacs development team.  Feature requests and suggestions are also
-more than welcome.  Use @kbd{M-x report-emacs-bug}, @pxref{Bugs, ,
-Bugs, emacs, Reporting Bugs}.
+more than welcome.  Use @kbd{M-x report-emacs-bug}, see @ref{Bugs, ,
+Reporting Bugs, emacs, The Emacs Editor}.
 
 When submitting a bug report, please try to describe in excruciating
 detail the steps required to reproduce the problem.  Also try to
-- 
2.30.2

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

[Eli Zaretskii]

> Date: Sat, 8 Jul 2023 22:31:16 +0200
> From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
> 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.

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

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

On 2023-07-09  09:24, Eli Zaretskii wrote:

Thanks for your thorough review.  Some follow-up comments and questions:

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

Yet another case where I tried to maintain consistency with the original
manual: It uses gpg-agent rather consistently (without @command) where I
probably would have used the proper name "GnuPG agent".

In any case it means changing existing text, not simply adding new text ...

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

... and same here.

My real problem here is to fix minor issues present in the existing text
and add my own changes in one commit, but you seem to be more relaxed
here, so I will just do that.

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

I thought that @vindex is somewhat reserved for Emacs variables that are
defined with @defvar.  So the variable index is more of an index for
everything "variable-like"?

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

Even if the whole text is a comment or to be @ignored?  In that case
should I probably also use @command{pinentry-emacs}, @file{pinentry.el},
etc. in the quoted paragraph?

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

[Eli Zaretskii]

> Date: Sun, 9 Jul 2023 12:18:39 +0200
> Cc: 64154@debbugs.gnu.org
> From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
> 
> >> +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.
> 
> Yet another case where I tried to maintain consistency with the original
> manual: It uses gpg-agent rather consistently (without @command) where I
> probably would have used the proper name "GnuPG agent".
> 
> In any case it means changing existing text, not simply adding new text ...

There's no need to fix everything (although you get bonus points for
doing so), it is enough not to add such problems in new text.

> I thought that @vindex is somewhat reserved for Emacs variables that are
> defined with @defvar.  So the variable index is more of an index for
> everything "variable-like"?

No, @vindex is for any variables.  (@defvar produces an index entry
automatically, so you don't have to add a @vindex.)

> >> +@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.
> 
> Even if the whole text is a comment or to be @ignored?

Well, if we want this text to be usable at some future point, yes.
Otherwise, why keep it?  And it isn't like making it right needs too
much work, so I think it's worth our while.

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

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

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

On 2023-07-09  13:26, Eli Zaretskii wrote:

> There's no need to fix everything (although you get bonus points for
> doing so), it is enough not to add such problems in new text.

Turned out that most references were mine, anyway, so little bonus.  I 
changed them to "GnuPG Agent" where the "abstract agent" more likely is 
being referred to and to @command{gpg-agent} where the "concrete 
command" is meant.  (The GnuPG manual is, um, extremely inconsistent in 
naming this thing, so nothing to be learnt from it.)

Other than that I followed your proposals, new patch attached.

There is this one open question regarding a completely different manual 
("Emacs auth-source") from one of my previous mails, though:

> Finally, I noticed that section "GnuPG and EasyPG Assistant
> Configuration(auth)" duplicates some of the information in section
> "Caching Passphrases(epa)", which means that these will be out of sync
> as soon as my changes have landed.  WDYT about that?

[-- Attachment #2: 0002-Add-basic-usage-information-and-fix-references.patch --]
[-- Type: text/x-patch, Size: 15152 bytes --]

From 0d3d5fc6afc25fefd7f48f5b7f520637a8670f7a Mon Sep 17 00:00:00 2001
From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
Date: Sun, 9 Jul 2023 16:17:27 +0200
Subject: [PATCH] Add basic usage information and fix references

* doc/misc/epa.texi (Top): Add menu entry for new node GnuPG Pinentry.
(Quick Start): Add information on and reference to basic GnuPG
configuration.
(Encrypting/decrypting gpg files): Add usage information.
(GnuPG version compatibility): Update version information.
(GnuPG Pinentry): Add new node.
(Caching Passphrases): Describe mandatory gpg-agent usage for GnuPG
2.0 and later.
(Overview, Encrypting/decrypting gpg files, GnuPG version compatibility)
(Caching Passphrases, Bug Reports): Fix references, terminology,
mark-up, and index entries.  (Bug#64154)
---
 doc/misc/epa.texi | 216 +++++++++++++++++++++++++++++++++++++---------
 1 file changed, 175 insertions(+), 41 deletions(-)

diff --git a/doc/misc/epa.texi b/doc/misc/epa.texi
index edfe37de816..917fd588593 100644
--- a/doc/misc/epa.texi
+++ b/doc/misc/epa.texi
@@ -70,6 +70,7 @@ Top
 * Quick start::
 * Commands::
 * GnuPG version compatibility::
+* GnuPG Pinentry::
 * Caching Passphrases::
 * Bug Reports::
 * GNU Free Documentation License::  The license for this documentation.
@@ -83,7 +84,8 @@ Overview
 @chapter Overview
 @cindex features of easypg assistant
 
-EasyPG Assistant provides the following features.
+EasyPG Assistant is an Emacs frontend application to @acronym{GnuPG,
+GNU Privacy Guard} that provides the following features:
 
 @itemize @bullet
 @item Key management.
@@ -97,6 +99,22 @@ Overview
 @node Quick start
 @chapter Quick Start
 @cindex introduction to easypg assistant
+@cindex gnupg documentation
+@cindex documentation on gnupg
+@cindex configuration of gnupg
+@cindex introduction to gnupg
+
+You can use EasyPG Assistant without any Emacs or GnuPG configuration
+whatsoever, for example to encrypt and decrypt files automatically
+with symmetric encryption, see @ref{Encrypting/decrypting gpg files}.
+However, to use the full set of EasyPG Assistant's functions you
+should have at least some minimum GnuPG configuration in place.
+
+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 a reference manual.
 
 EasyPG Assistant commands are prefixed by @samp{epa-}.  For example,
 
@@ -410,6 +428,44 @@ Encrypting/decrypting gpg files
 Similarly, when you save the buffer to a @file{foo.gpg} file,
 encrypted data is written.
 
+When you save a buffer to an encrypted file for the first time, EasyPG
+Assistant presents you a list of keys in a buffer @file{*Keys*} where
+you can select recipients for encryption.  @xref{Key management}, for
+a description of the format of that buffer.  You can streamline this
+recipient selection step by customizing variables
+@code{epa-file-encrypt-to} and @code{epa-file-select-keys} described
+further below in this section.
+
+@cindex symmetric encryption, passphrase entry for
+If you do not select any recipient during this step, EasyPG Assistant
+uses symmetric encryption.  As a consequence, you have to enter the
+passphrase twice for every buffer save and every so often for file
+reads, since the GnuPG Agent caches your passphrase for file reads at
+least for some time, but not for buffer saves.  @xref{Caching
+Passphrases}, for more information.
+
+@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 will use public key
+encryption for that file.  Since GnuPG performs encryption with your
+public key, it does not prompt for a passphrase for the buffer save,
+but it will prompt for your passphrase for file reads every now and
+then, depending on the GnuPG Agent cache configuration.
+
+@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} (@pxref{Unique File Names, ,
+Generating Unique File Names, elisp, GNU Emacs Lisp Reference
+Manual}).  If you want to be sure not to leave any plain-text traces,
+use an encrypted file systems at least for that directory.
+
 The file name pattern for encrypted files can be controlled by
 @code{epa-file-name-regexp}.
 
@@ -446,11 +502,11 @@ Encrypting/decrypting gpg files
 Control whether or not to pop up the key selection dialog.
 @end defvar
 
-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.
 @vindex epa-file-encrypt-to
+For frequently visited files, it might be a good idea to tell Emacs
+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.
 
 For example, if you want an Elisp file to be encrypted with a
 public key associated with an email address @samp{ueno@@unixuser.org},
@@ -478,6 +534,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 be used.  Instead, consider using the GnuPG Agent, which
+in many cases can do the same job, and does it in a safer way.
+@xref{Caching Passphrases}, for more information.
 @end defvar
 
 @defvar epa-file-inhibit-auto-save
@@ -507,10 +568,17 @@ GnuPG version compatibility
 @cindex version compatibility with gnupg
 @cindex compatibility with gnupg
 
-As of February 2016, there are three active branches of GnuPG: 2.1,
-2.0, 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.
+As of June 2023, there are three active branches of GnuPG: 2.4, 2.2,
+and 1.4.  GnuPG versions 2.4.1 and later suffer from
+@uref{https://dev.gnupg.org/T6481, GnuPG bug T6481} and are hardly
+usable with Emacs.  There is a patch for that bug available at least
+for GnuPG version 2.4.1, which your operating system or distribution
+might provide already.  GnuPG 1.4 is considered a legacy version.
+
+Besides that, all of those branches mentioned above should work
+flawlessly with Emacs with basic use-cases.  They have, however, some
+incompatible characteristics, which might be visible when used from
+Emacs.
 
 @itemize
 @item
@@ -519,23 +587,91 @@ GnuPG version compatibility
 
 @item
 GnuPG 2.1 uses a fixed address for the Unix domain socket used to
-communicate with gpg-agent.  The @code{GPG_AGENT_INFO} environment
-variable, which is used by GnuPG 2.0 and 1.4, is ignored.  That means,
-if your system has both GnuPG 2.1 and 1.4, the gpg command from GnuPG
-1.4 is not able to use gpg-agent provided by 2.1 (at least out of box).
+communicate with @command{gpg-agent}.  The @code{GPG_AGENT_INFO}
+environment variable, which is used by GnuPG 2.0 and 1.4, is ignored.
+That means, if your system has both GnuPG 2.1 and 1.4, the gpg command
+from GnuPG 1.4 is not able to use @command{gpg-agent} provided by 2.1
+(at least out of box).
 
 @item
 GnuPG 2.1 (2.1.5 or later) has a mechanism to direct the Pinentry
-password prompt to the Emacs minibuffer@footnote{To enable this
-feature, add @samp{allow-emacs-pinentry} to
-@file{~/.gnupg/gpg-agent.conf} and let gpg-agent reload the
-configuration, with: @samp{gpgconf --reload gpg-agent}}, which would
-be useful when you use Emacs remotely or from a text-only terminal.
-That feature is not available in other versions, and more
-specifically, with 2.0 (as of 2.0.29), there is no way to avoid the
-graphical prompt.
+password prompt to the Emacs minibuffer.  @xref{GnuPG Pinentry}.
 @end itemize
 
+@node GnuPG Pinentry
+@chapter GnuPG Pinentry
+@cindex gnupg pinentry
+@cindex pinentry provided by gnupg
+
+An important component of the GnuPG suite is the Pinentry, which
+allows for secure entry of passphrases requested by GnuPG.  GnuPG
+delivers various different programs as Pinentry, ranging from bland
+TTY-only @command{pinentry-tty} to fancy graphical dialogs for various
+desktop environments, like @command{pinentry-gnome3}.  Your operating
+system usually determines which of these is used by default.
+
+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 see @ref{Caching Passphrases}.
+
+@cindex pinentry, emacs as
+With some configuration Emacs can also play the role of a Pinentry.
+The most natural choice, available with GnuPG 2.1.5 and later, is to
+use Emacs itself as Pinentry for requests that are triggered by Emacs.
+For example, if you open a file whose name ends with @file{.gpg} using
+automatic decryption, you most likely also want to enter the
+passphrase for that request in Emacs.
+
+@cindex loopback pinentry
+This so called @dfn{loopback Pinentry} has the added benefit that it
+works also when you use Emacs remotely or from a text-only terminal.
+To enable it:
+
+@enumerate
+@item
+@vindex allow-loopback-pinentry
+Ensure that option @code{allow-loopback-pinentry} is configured for
+@command{gpg-agent}, which should be the default.  @xref{Agent
+Options, , Option Summary, gnupg, Using the GNU Privacy Guard}.
+
+@item
+@vindex epg-pinentry-mode
+Customize variable @code{epg-pinentry-mode} to @code{loopback} in
+Emacs.
+@end enumerate
+
+There are other options available to use Emacs as Pinentry, you might
+come across a Pinentry called @command{pinentry-emacs} or
+@command{gpg-agent} option @code{allow-emacs-pinentry}.  However,
+these are considered insecure or semi-obsolete and might not be
+supported by your operating system or distribution.  For example,
+Debian GNU/Linux supports only the loopback Pinentry described above.
+
+@ignore
+In case somebody requests these:
+
+Use Emacs for all GnuPG requests:
+
+Make @command{pinentry-emacs} the default Pinentry by means of your
+operating system.  Install package @file{pinentry.el} from GNU ELPA
+and execute @kbd{M-x pinentry-start} to start the Emacs Pinentry
+service.  @emph{All} GnuPG passphrase requests should then result in a
+minibuffer prompt in the running Emacs.  If Emacs or the Emacs
+Pinentry service are not running, passphrase requests fail.
+
+Use Emacs for all GnuPG requests with other Pinentry as fallback:
+
+Ensure the other Pinentry supports Emacs; @command{pinentry-curses}
+does, for example.  Configure @command{gpg-agent} option
+@code{allow-emacs-pinentry}.  Set environment variable
+@code{INSIDE_EMACS} for the calling process.  Install package
+@file{pinentry.el}.  Now if Emacs is running and @kbd{M-x
+pinentry-start} has been executed, all GnuPG passphrase requests
+should result in a minibuffer prompt in the running Emacs.  If Emacs
+or the Emacs Pinentry service are not running, GnuPG uses the other
+Pinentry instead.
+@end ignore
+
 @node Caching Passphrases
 @chapter Caching Passphrases
 @cindex caching passphrases
@@ -545,35 +681,33 @@ Caching Passphrases
 Typing passphrases is a troublesome task if you frequently open and
 close the same file.  GnuPG and EasyPG Assistant provide mechanisms to
 remember your passphrases for a limited time.  Using these, you only
-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 (symmetric or public key),
-and whether or not you want to use gpg-agent.  Here are some
-questions:
+need to re-enter the passphrase occasionally.  However, the
+configuration is a bit confusing since it depends on your GnuPG
+installation (@pxref{GnuPG version compatibility}), encryption method
+(symmetric or public key), and whether or not you want to use
+GnuPG Agent.  As an additional constraint, use of the GnuPG Agent is
+mandatory for GnuPG 2.0 and later.  Here are some questions:
 
 @enumerate
-@item Do you use GnuPG version 2.1 or 2.0 instead of GnuPG version 1.4?
+@item Do you use GnuPG version 2.0 or later instead of GnuPG version 1.4?
 @item Do you use symmetric encryption rather than public key encryption?
-@item Do you want to use gpg-agent?
+@item Do you want to use GnuPG Agent?
 @end enumerate
 
 Here are configurations depending on your answers:
 
 @multitable {111} {222} {333} {configuration configuration configuration}
 @item @b{1} @tab @b{2} @tab @b{3} @tab Configuration
-@item Yes @tab Yes @tab Yes @tab Set up gpg-agent.
-@item Yes @tab Yes @tab No @tab You can't, without gpg-agent.
-@item Yes @tab No @tab Yes @tab Set up gpg-agent.
-@item Yes @tab No @tab No @tab You can't, without gpg-agent.
-@item No @tab Yes @tab Yes @tab Set up elisp passphrase cache.
-@item No @tab Yes @tab No @tab Set up elisp passphrase cache.
-@item No @tab No @tab Yes @tab Set up gpg-agent.
-@item No @tab No @tab No @tab You can't, without gpg-agent.
+@item Yes   @tab Yes   @tab Must  @tab Set up GnuPG Agent.
+@item Yes   @tab No    @tab Must  @tab Set up GnuPG Agent.
+@item No    @tab Yes   @tab Yes   @tab Set up elisp passphrase cache.
+@item No    @tab Yes   @tab No    @tab Set up elisp passphrase cache.
+@item No    @tab No    @tab Yes   @tab Set up GnuPG Agent.
+@item No    @tab No    @tab No    @tab You can't, without GnuPG Agent.
 @end multitable
 
-To set up gpg-agent, follow the instruction in GnuPG manual.
-@pxref{Invoking GPG-AGENT, , Invoking GPG-AGENT, gnupg}.
+To set up GnuPG Agent, follow the instruction in @ref{Invoking
+GPG-AGENT, , , gnupg, Using the GNU Privacy Guard}.
 
 To set up elisp passphrase cache, set
 @code{epa-file-cache-passphrase-for-symmetric-encryption}.
@@ -586,8 +720,8 @@ Bug Reports
 
 Bugs and problems with EasyPG Assistant are actively worked on by the
 Emacs development team.  Feature requests and suggestions are also
-more than welcome.  Use @kbd{M-x report-emacs-bug}, @pxref{Bugs, ,
-Bugs, emacs, Reporting Bugs}.
+more than welcome.  Use @kbd{M-x report-emacs-bug}, see @ref{Bugs, ,
+Reporting Bugs, emacs, The Emacs Editor}.
 
 When submitting a bug report, please try to describe in excruciating
 detail the steps required to reproduce the problem.  Also try to
-- 
2.30.2

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

[Eli Zaretskii]

> Date: Sun, 9 Jul 2023 16:41:05 +0200
> From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
> Cc: 64154@debbugs.gnu.org
> 
> There is this one open question regarding a completely different manual 
> ("Emacs auth-source") from one of my previous mails, though:
> 
> > Finally, I noticed that section "GnuPG and EasyPG Assistant
> > Configuration(auth)" duplicates some of the information in section
> > "Caching Passphrases(epa)", which means that these will be out of sync
> > as soon as my changes have landed.  WDYT about that?

Convert the other text to a simple cross-reference to the main manual,
and add whatever info is missing from the main manual, if needed.

Thanks.

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

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

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

On 2023-07-11  13:02, Eli Zaretskii wrote:

> Convert the other text to a simple cross-reference to the main manual,
> and add whatever info is missing from the main manual, if needed.

Here it is, for convenience together with both previous patches:

0001-Add-concept-index-title-case-structure-titles.patch

Sent in https://debbugs.gnu.org/cgi/bugreport.cgi?bug=64154#71, LGTMed
by you in #77.

0002-Add-basic-usage-information-and-fix-references.patch

Sent in https://debbugs.gnu.org/cgi/bugreport.cgi?bug=64154#92 as a
result of your previous review.

0003-Replace-duplicate-text-from-epa.texi-by-a-reference.patch

Hope these are all OK to you.  If so please commit and merge to 
emacs-29.  I can close this bug, then.

Thanks

[-- Attachment #2: 0001-Add-concept-index-title-case-structure-titles.patch --]
[-- Type: text/x-patch, Size: 8852 bytes --]

From 3a71ed23947f0701b2c640355264693d2d77e675 Mon Sep 17 00:00:00 2001
From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
Date: Sun, 2 Jul 2023 13:39:48 +0200
Subject: [PATCH 1/3] Add concept index, title-case structure titles

* doc/misc/epa.texi (Top, Overview, Commands, Key management)
(Cryptographic operations on regions, Cryptographic operations on files)
(Dired integration, Mail-mode integration)
(Encrypting/decrypting gpg files, Querying a key server)
(GnuPG version compatibility, Caching Passphrases)
(GNU Free Documentation License): Add concept index, title-case
structure titles.  (Bug#64154)
---
 doc/misc/epa.texi | 77 ++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 66 insertions(+), 11 deletions(-)

diff --git a/doc/misc/epa.texi b/doc/misc/epa.texi
index 6f63a3d7ba0..edfe37de816 100644
--- a/doc/misc/epa.texi
+++ b/doc/misc/epa.texi
@@ -43,7 +43,10 @@
 @contents
 
 @node Top
-@top EasyPG Assistant user's manual
+@top EasyPG Assistant User's Manual
+@cindex easypg assistant
+@cindex gnu privacy guard
+@cindex gnupg
 
 EasyPG Assistant is an Emacs user interface to GNU Privacy Guard
 (GnuPG, @pxref{Top, , Top, gnupg, Using the GNU Privacy Guard}).
@@ -56,6 +59,12 @@ Top
 @insertcopying
 @end ifnottex
 
+@c Unfortunately the node names of this manual are not very consistent
+@c w.r.t. their case.  However, case is significant in node names, so
+@c we probably better should not change these to not break any
+@c external references.  Things are more relaxed for structure titles,
+@c so we consistently updated them to title-case.
+
 @menu
 * Overview::
 * Quick start::
@@ -64,6 +73,7 @@ Top
 * Caching Passphrases::
 * Bug Reports::
 * GNU Free Documentation License::  The license for this documentation.
+* Concept Index::
 * Key Index::
 * Function Index::
 * Variable Index::
@@ -71,6 +81,7 @@ Top
 
 @node Overview
 @chapter Overview
+@cindex features of easypg assistant
 
 EasyPG Assistant provides the following features.
 
@@ -84,7 +95,8 @@ Overview
 @end itemize
 
 @node Quick start
-@chapter Quick start
+@chapter Quick Start
+@cindex introduction to easypg assistant
 
 EasyPG Assistant commands are prefixed by @samp{epa-}.  For example,
 
@@ -118,7 +130,11 @@ Commands
 @end menu
 
 @node Key management
-@section Key management
+@section Key Management
+@cindex key management
+
+@cindex key ring, browsing
+@cindex browse key ring
 Probably the first step of using EasyPG Assistant is to browse your
 keyring.  @kbd{M-x epa-list-keys} is corresponding to @samp{gpg
 --list-keys} from the command line.
@@ -157,6 +173,7 @@ Key management
         Fingerprint: 9003 D76B 73B7 4A8A E588  10AF 4447 461B 2A9B EA2D
 @end example
 
+@cindex private key ring, browsing
 @noindent
 To browse your private keyring, use @kbd{M-x epa-list-secret-keys}.
 
@@ -172,12 +189,14 @@ Key management
 Below are other commands related to key management.  Some of them take
 a file as input/output, and others take the current region.
 
+@cindex insert keys
 @deffn Command epa-insert-keys keys
 Insert selected @var{keys} after the point.  It will let you select
 keys before insertion.  By default, it will encode keys in the OpenPGP
 armor format.
 @end deffn
 
+@cindex import keys
 @deffn Command epa-import-keys file
 Import keys from @var{file} to your keyring.
 @end deffn
@@ -195,14 +214,18 @@ Key management
 applies @code{epa-import-keys-region} to each of them.
 @end deffn
 
+@cindex delete keys
 @deffn Command epa-delete-keys allow-secret
 Delete selected keys.  If @var{allow-secret} is non-@code{nil}, it
 also delete the secret keys.
 @end deffn
 
 @node Cryptographic operations on regions
-@section Cryptographic operations on regions
+@section Cryptographic Operations on Regions
+@cindex cryptographic operations on regions
+@cindex region operations, cryptographic
 
+@cindex decrypt region
 @deffn Command epa-decrypt-region start end
 Decrypt the current region between @var{start} and @var{end}.  It
 replaces the region with the decrypted text.
@@ -216,6 +239,7 @@ Cryptographic operations on regions
 command does not alter the original text around armors.
 @end deffn
 
+@cindex verify region
 @deffn Command epa-verify-region start end
 Verify the current region between @var{start} and @var{end}.  It sends
 the verification result to the minibuffer or a popup window.  It
@@ -231,6 +255,7 @@ Cryptographic operations on regions
 not alter the original text around OpenPGP cleartext blocks.
 @end deffn
 
+@cindex sign region
 @deffn Command epa-sign-region start end signers type
 Sign the current region between @var{start} and @var{end}.  By
 default, it creates a cleartext signature.  If a prefix argument is
@@ -238,6 +263,7 @@ Cryptographic operations on regions
 type.
 @end deffn
 
+@cindex encrypt region
 @deffn Command epa-encrypt-region start end recipients sign signers
 Encrypt the current region between @var{start} and @var{end}.  It will
 let you select recipients.  If a prefix argument is given, it will
@@ -246,28 +272,37 @@ Cryptographic operations on regions
 @end deffn
 
 @node Cryptographic operations on files
-@section Cryptographic operations on files
+@section Cryptographic Operations on Files
+@cindex cryptographic operations on files
+@cindex file operations, cryptographic
 
+@cindex decrypt file
 @deffn Command epa-decrypt-file file &optional output
 Decrypt @var{file}.  If you do not specify the name @var{output} to
 use for the decrypted file, this function prompts for the value to use.
 @end deffn
 
+@cindex verify file
 @deffn Command epa-verify-file file
 Verify @var{file}.
 @end deffn
 
+@cindex sign file
 @deffn Command epa-sign-file file signers type
 Sign @var{file}.  If a prefix argument is given, it will let you
 select signing keys, and then a signature type.
 @end deffn
 
+@cindex encrypt file
 @deffn Command epa-encrypt-file file recipients
 Encrypt @var{file}.  It will let you select recipients.
 @end deffn
 
 @node Dired integration
-@section Dired integration
+@section Dired Integration
+@cindex dired integration
+@cindex directory operations
+@cindex multiple file operations
 
 EasyPG Assistant extends Dired Mode for GNU Emacs to allow users to
 easily do cryptographic operations on files.  For example,
@@ -306,7 +341,9 @@ Dired integration
 @end table
 
 @node Mail-mode integration
-@section Mail-mode integration
+@section Mail-Mode Integration
+@cindex mail-mode integration
+@cindex sending signed/encrypted mails
 
 EasyPG Assistant provides a minor mode @code{epa-mail-mode} to help
 user compose inline OpenPGP messages.  Inline OpenPGP is a traditional
@@ -361,7 +398,12 @@ Mail-mode integration
 @end table
 
 @node Encrypting/decrypting gpg files
-@section Encrypting/decrypting gpg files
+@section Encrypting and Decrypting gpg Files
+@cindex encrypting gpg files
+@cindex decrypting gpg files
+@cindex gpg files, encrypting and decrypting
+@cindex automatic file encryption and decryption
+
 By default, every file whose name ends with @file{.gpg} will be
 treated as encrypted.  That is, when you open such a file, the
 decrypted text is inserted in the buffer rather than encrypted one.
@@ -444,7 +486,9 @@ Encrypting/decrypting gpg files
 @end defvar
 
 @node Querying a key server
-@section Querying a key server
+@section Querying a Key Server
+@cindex query key server
+@cindex key server, querying
 
 The @code{epa-search-keys} command can be used to query a
 @acronym{GPG} key server.  Emacs will then pop up a buffer that lists
@@ -457,9 +501,11 @@ Querying a key server
 
 The @code{epa-keyserver} variable says which server to query.
 
-
 @node GnuPG version compatibility
-@chapter GnuPG version compatibility
+@chapter GnuPG Version Compatibility
+@cindex gnupg version compatibility
+@cindex version compatibility with gnupg
+@cindex compatibility with gnupg
 
 As of February 2016, there are three active branches of GnuPG: 2.1,
 2.0, and 1.4.  All those branches should work flawlessly with Emacs
@@ -492,6 +538,9 @@ GnuPG version compatibility
 
 @node Caching Passphrases
 @chapter Caching Passphrases
+@cindex caching passphrases
+@cindex entering passphrases
+@cindex passphrases, entering and caching
 
 Typing passphrases is a troublesome task if you frequently open and
 close the same file.  GnuPG and EasyPG Assistant provide mechanisms to
@@ -532,6 +581,8 @@ Caching Passphrases
 
 @node Bug Reports
 @chapter Bug Reports
+@cindex bug reports
+@cindex reporting bugs
 
 Bugs and problems with EasyPG Assistant are actively worked on by the
 Emacs development team.  Feature requests and suggestions are also
@@ -556,6 +607,10 @@ GNU Free Documentation License
 @appendix GNU Free Documentation License
 @include doclicense.texi
 
+@node Concept Index
+@unnumbered Concept Index
+@printindex cp
+
 @node Key Index
 @unnumbered Key Index
 @printindex ky
-- 
2.30.2


[-- Attachment #3: 0002-Add-basic-usage-information-and-fix-references.patch --]
[-- Type: text/x-patch, Size: 15156 bytes --]

From 681f5e7bb0d1225006c7c6a7ca5ec84869277692 Mon Sep 17 00:00:00 2001
From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
Date: Sun, 9 Jul 2023 16:17:27 +0200
Subject: [PATCH 2/3] Add basic usage information and fix references

* doc/misc/epa.texi (Top): Add menu entry for new node GnuPG Pinentry.
(Quick Start): Add information on and reference to basic GnuPG
configuration.
(Encrypting/decrypting gpg files): Add usage information.
(GnuPG version compatibility): Update version information.
(GnuPG Pinentry): Add new node.
(Caching Passphrases): Describe mandatory gpg-agent usage for GnuPG
2.0 and later.
(Overview, Encrypting/decrypting gpg files, GnuPG version compatibility)
(Caching Passphrases, Bug Reports): Fix references, terminology,
mark-up, and index entries.  (Bug#64154)
---
 doc/misc/epa.texi | 216 +++++++++++++++++++++++++++++++++++++---------
 1 file changed, 175 insertions(+), 41 deletions(-)

diff --git a/doc/misc/epa.texi b/doc/misc/epa.texi
index edfe37de816..917fd588593 100644
--- a/doc/misc/epa.texi
+++ b/doc/misc/epa.texi
@@ -70,6 +70,7 @@ Top
 * Quick start::
 * Commands::
 * GnuPG version compatibility::
+* GnuPG Pinentry::
 * Caching Passphrases::
 * Bug Reports::
 * GNU Free Documentation License::  The license for this documentation.
@@ -83,7 +84,8 @@ Overview
 @chapter Overview
 @cindex features of easypg assistant
 
-EasyPG Assistant provides the following features.
+EasyPG Assistant is an Emacs frontend application to @acronym{GnuPG,
+GNU Privacy Guard} that provides the following features:
 
 @itemize @bullet
 @item Key management.
@@ -97,6 +99,22 @@ Overview
 @node Quick start
 @chapter Quick Start
 @cindex introduction to easypg assistant
+@cindex gnupg documentation
+@cindex documentation on gnupg
+@cindex configuration of gnupg
+@cindex introduction to gnupg
+
+You can use EasyPG Assistant without any Emacs or GnuPG configuration
+whatsoever, for example to encrypt and decrypt files automatically
+with symmetric encryption, see @ref{Encrypting/decrypting gpg files}.
+However, to use the full set of EasyPG Assistant's functions you
+should have at least some minimum GnuPG configuration in place.
+
+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 a reference manual.
 
 EasyPG Assistant commands are prefixed by @samp{epa-}.  For example,
 
@@ -410,6 +428,44 @@ Encrypting/decrypting gpg files
 Similarly, when you save the buffer to a @file{foo.gpg} file,
 encrypted data is written.
 
+When you save a buffer to an encrypted file for the first time, EasyPG
+Assistant presents you a list of keys in a buffer @file{*Keys*} where
+you can select recipients for encryption.  @xref{Key management}, for
+a description of the format of that buffer.  You can streamline this
+recipient selection step by customizing variables
+@code{epa-file-encrypt-to} and @code{epa-file-select-keys} described
+further below in this section.
+
+@cindex symmetric encryption, passphrase entry for
+If you do not select any recipient during this step, EasyPG Assistant
+uses symmetric encryption.  As a consequence, you have to enter the
+passphrase twice for every buffer save and every so often for file
+reads, since the GnuPG Agent caches your passphrase for file reads at
+least for some time, but not for buffer saves.  @xref{Caching
+Passphrases}, for more information.
+
+@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 will use public key
+encryption for that file.  Since GnuPG performs encryption with your
+public key, it does not prompt for a passphrase for the buffer save,
+but it will prompt for your passphrase for file reads every now and
+then, depending on the GnuPG Agent cache configuration.
+
+@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} (@pxref{Unique File Names, ,
+Generating Unique File Names, elisp, GNU Emacs Lisp Reference
+Manual}).  If you want to be sure not to leave any plain-text traces,
+use an encrypted file systems at least for that directory.
+
 The file name pattern for encrypted files can be controlled by
 @code{epa-file-name-regexp}.
 
@@ -446,11 +502,11 @@ Encrypting/decrypting gpg files
 Control whether or not to pop up the key selection dialog.
 @end defvar
 
-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.
 @vindex epa-file-encrypt-to
+For frequently visited files, it might be a good idea to tell Emacs
+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.
 
 For example, if you want an Elisp file to be encrypted with a
 public key associated with an email address @samp{ueno@@unixuser.org},
@@ -478,6 +534,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 be used.  Instead, consider using the GnuPG Agent, which
+in many cases can do the same job, and does it in a safer way.
+@xref{Caching Passphrases}, for more information.
 @end defvar
 
 @defvar epa-file-inhibit-auto-save
@@ -507,10 +568,17 @@ GnuPG version compatibility
 @cindex version compatibility with gnupg
 @cindex compatibility with gnupg
 
-As of February 2016, there are three active branches of GnuPG: 2.1,
-2.0, 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.
+As of June 2023, there are three active branches of GnuPG: 2.4, 2.2,
+and 1.4.  GnuPG versions 2.4.1 and later suffer from
+@uref{https://dev.gnupg.org/T6481, GnuPG bug T6481} and are hardly
+usable with Emacs.  There is a patch for that bug available at least
+for GnuPG version 2.4.1, which your operating system or distribution
+might provide already.  GnuPG 1.4 is considered a legacy version.
+
+Besides that, all of those branches mentioned above should work
+flawlessly with Emacs with basic use-cases.  They have, however, some
+incompatible characteristics, which might be visible when used from
+Emacs.
 
 @itemize
 @item
@@ -519,23 +587,91 @@ GnuPG version compatibility
 
 @item
 GnuPG 2.1 uses a fixed address for the Unix domain socket used to
-communicate with gpg-agent.  The @code{GPG_AGENT_INFO} environment
-variable, which is used by GnuPG 2.0 and 1.4, is ignored.  That means,
-if your system has both GnuPG 2.1 and 1.4, the gpg command from GnuPG
-1.4 is not able to use gpg-agent provided by 2.1 (at least out of box).
+communicate with @command{gpg-agent}.  The @code{GPG_AGENT_INFO}
+environment variable, which is used by GnuPG 2.0 and 1.4, is ignored.
+That means, if your system has both GnuPG 2.1 and 1.4, the gpg command
+from GnuPG 1.4 is not able to use @command{gpg-agent} provided by 2.1
+(at least out of box).
 
 @item
 GnuPG 2.1 (2.1.5 or later) has a mechanism to direct the Pinentry
-password prompt to the Emacs minibuffer@footnote{To enable this
-feature, add @samp{allow-emacs-pinentry} to
-@file{~/.gnupg/gpg-agent.conf} and let gpg-agent reload the
-configuration, with: @samp{gpgconf --reload gpg-agent}}, which would
-be useful when you use Emacs remotely or from a text-only terminal.
-That feature is not available in other versions, and more
-specifically, with 2.0 (as of 2.0.29), there is no way to avoid the
-graphical prompt.
+password prompt to the Emacs minibuffer.  @xref{GnuPG Pinentry}.
 @end itemize
 
+@node GnuPG Pinentry
+@chapter GnuPG Pinentry
+@cindex gnupg pinentry
+@cindex pinentry provided by gnupg
+
+An important component of the GnuPG suite is the Pinentry, which
+allows for secure entry of passphrases requested by GnuPG.  GnuPG
+delivers various different programs as Pinentry, ranging from bland
+TTY-only @command{pinentry-tty} to fancy graphical dialogs for various
+desktop environments, like @command{pinentry-gnome3}.  Your operating
+system usually determines which of these is used by default.
+
+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 see @ref{Caching Passphrases}.
+
+@cindex pinentry, emacs as
+With some configuration Emacs can also play the role of a Pinentry.
+The most natural choice, available with GnuPG 2.1.5 and later, is to
+use Emacs itself as Pinentry for requests that are triggered by Emacs.
+For example, if you open a file whose name ends with @file{.gpg} using
+automatic decryption, you most likely also want to enter the
+passphrase for that request in Emacs.
+
+@cindex loopback pinentry
+This so called @dfn{loopback Pinentry} has the added benefit that it
+works also when you use Emacs remotely or from a text-only terminal.
+To enable it:
+
+@enumerate
+@item
+@vindex allow-loopback-pinentry
+Ensure that option @code{allow-loopback-pinentry} is configured for
+@command{gpg-agent}, which should be the default.  @xref{Agent
+Options, , Option Summary, gnupg, Using the GNU Privacy Guard}.
+
+@item
+@vindex epg-pinentry-mode
+Customize variable @code{epg-pinentry-mode} to @code{loopback} in
+Emacs.
+@end enumerate
+
+There are other options available to use Emacs as Pinentry, you might
+come across a Pinentry called @command{pinentry-emacs} or
+@command{gpg-agent} option @code{allow-emacs-pinentry}.  However,
+these are considered insecure or semi-obsolete and might not be
+supported by your operating system or distribution.  For example,
+Debian GNU/Linux supports only the loopback Pinentry described above.
+
+@ignore
+In case somebody requests these:
+
+Use Emacs for all GnuPG requests:
+
+Make @command{pinentry-emacs} the default Pinentry by means of your
+operating system.  Install package @file{pinentry.el} from GNU ELPA
+and execute @kbd{M-x pinentry-start} to start the Emacs Pinentry
+service.  @emph{All} GnuPG passphrase requests should then result in a
+minibuffer prompt in the running Emacs.  If Emacs or the Emacs
+Pinentry service are not running, passphrase requests fail.
+
+Use Emacs for all GnuPG requests with other Pinentry as fallback:
+
+Ensure the other Pinentry supports Emacs; @command{pinentry-curses}
+does, for example.  Configure @command{gpg-agent} option
+@code{allow-emacs-pinentry}.  Set environment variable
+@code{INSIDE_EMACS} for the calling process.  Install package
+@file{pinentry.el}.  Now if Emacs is running and @kbd{M-x
+pinentry-start} has been executed, all GnuPG passphrase requests
+should result in a minibuffer prompt in the running Emacs.  If Emacs
+or the Emacs Pinentry service are not running, GnuPG uses the other
+Pinentry instead.
+@end ignore
+
 @node Caching Passphrases
 @chapter Caching Passphrases
 @cindex caching passphrases
@@ -545,35 +681,33 @@ Caching Passphrases
 Typing passphrases is a troublesome task if you frequently open and
 close the same file.  GnuPG and EasyPG Assistant provide mechanisms to
 remember your passphrases for a limited time.  Using these, you only
-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 (symmetric or public key),
-and whether or not you want to use gpg-agent.  Here are some
-questions:
+need to re-enter the passphrase occasionally.  However, the
+configuration is a bit confusing since it depends on your GnuPG
+installation (@pxref{GnuPG version compatibility}), encryption method
+(symmetric or public key), and whether or not you want to use
+GnuPG Agent.  As an additional constraint, use of the GnuPG Agent is
+mandatory for GnuPG 2.0 and later.  Here are some questions:
 
 @enumerate
-@item Do you use GnuPG version 2.1 or 2.0 instead of GnuPG version 1.4?
+@item Do you use GnuPG version 2.0 or later instead of GnuPG version 1.4?
 @item Do you use symmetric encryption rather than public key encryption?
-@item Do you want to use gpg-agent?
+@item Do you want to use GnuPG Agent?
 @end enumerate
 
 Here are configurations depending on your answers:
 
 @multitable {111} {222} {333} {configuration configuration configuration}
 @item @b{1} @tab @b{2} @tab @b{3} @tab Configuration
-@item Yes @tab Yes @tab Yes @tab Set up gpg-agent.
-@item Yes @tab Yes @tab No @tab You can't, without gpg-agent.
-@item Yes @tab No @tab Yes @tab Set up gpg-agent.
-@item Yes @tab No @tab No @tab You can't, without gpg-agent.
-@item No @tab Yes @tab Yes @tab Set up elisp passphrase cache.
-@item No @tab Yes @tab No @tab Set up elisp passphrase cache.
-@item No @tab No @tab Yes @tab Set up gpg-agent.
-@item No @tab No @tab No @tab You can't, without gpg-agent.
+@item Yes   @tab Yes   @tab Must  @tab Set up GnuPG Agent.
+@item Yes   @tab No    @tab Must  @tab Set up GnuPG Agent.
+@item No    @tab Yes   @tab Yes   @tab Set up elisp passphrase cache.
+@item No    @tab Yes   @tab No    @tab Set up elisp passphrase cache.
+@item No    @tab No    @tab Yes   @tab Set up GnuPG Agent.
+@item No    @tab No    @tab No    @tab You can't, without GnuPG Agent.
 @end multitable
 
-To set up gpg-agent, follow the instruction in GnuPG manual.
-@pxref{Invoking GPG-AGENT, , Invoking GPG-AGENT, gnupg}.
+To set up GnuPG Agent, follow the instruction in @ref{Invoking
+GPG-AGENT, , , gnupg, Using the GNU Privacy Guard}.
 
 To set up elisp passphrase cache, set
 @code{epa-file-cache-passphrase-for-symmetric-encryption}.
@@ -586,8 +720,8 @@ Bug Reports
 
 Bugs and problems with EasyPG Assistant are actively worked on by the
 Emacs development team.  Feature requests and suggestions are also
-more than welcome.  Use @kbd{M-x report-emacs-bug}, @pxref{Bugs, ,
-Bugs, emacs, Reporting Bugs}.
+more than welcome.  Use @kbd{M-x report-emacs-bug}, see @ref{Bugs, ,
+Reporting Bugs, emacs, The Emacs Editor}.
 
 When submitting a bug report, please try to describe in excruciating
 detail the steps required to reproduce the problem.  Also try to
-- 
2.30.2


[-- Attachment #4: 0003-Replace-duplicate-text-from-epa.texi-by-a-reference.patch --]
[-- Type: text/x-patch, Size: 2700 bytes --]

From 0853163a552edae577fa44b5213a81eb7769d320 Mon Sep 17 00:00:00 2001
From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
Date: Tue, 11 Jul 2023 21:57:31 +0200
Subject: [PATCH 3/3] Replace duplicate text from epa.texi by a reference

* doc/misc/auth.texi (GnuPG and EasyPG Assistant Configuration):
Replace duplicate text from epa.texi by a reference to
that. (Bug#64154)
---
 doc/misc/auth.texi | 43 ++++++-------------------------------------
 1 file changed, 6 insertions(+), 37 deletions(-)

diff --git a/doc/misc/auth.texi b/doc/misc/auth.texi
index 03484950e01..7b4e8fcfb39 100644
--- a/doc/misc/auth.texi
+++ b/doc/misc/auth.texi
@@ -675,43 +675,12 @@ GnuPG and EasyPG Assistant Configuration
 read the GnuPG encrypted @file{.gpg} file first, before
 the unencrypted file.
 
-There is an option @code{auto-encryption-mode} to automatically
-decrypt @file{*.gpg} files.  It is enabled by default.
-
-If you want your GnuPG passwords to be cached, set up @code{gpg-agent}
-or EasyPG Assistant
-(@pxref{Caching Passphrases, , Caching Passphrases, epa}).
-
-To quick start, here are some questions:
-
-@itemize
-@item
-Do you use GnuPG version 2 instead of GnuPG version 1?
-@item
-Do you use symmetric encryption rather than public key encryption?
-@item
-Do you want to use gpg-agent?
-@end itemize
-
-Here are configurations depending on your answers:
-
-@multitable {111} {222} {333} {configuration configuration configuration}
-@item @b{1} @tab @b{2} @tab @b{3} @tab Configuration
-@item Yes @tab Yes @tab Yes @tab Set up gpg-agent.
-@item Yes @tab Yes @tab No @tab You can't, without gpg-agent.
-@item Yes @tab No @tab Yes @tab Set up gpg-agent.
-@item Yes @tab No @tab No @tab You can't, without gpg-agent.
-@item No @tab Yes @tab Yes @tab Set up elisp passphrase cache.
-@item No @tab Yes @tab No @tab Set up elisp passphrase cache.
-@item No @tab No @tab Yes @tab Set up gpg-agent.
-@item No @tab No @tab No @tab You can't, without gpg-agent.
-@end multitable
-
-To set up gpg-agent, follow the instruction in GnuPG manual
-(@pxref{Invoking GPG-AGENT, , Invoking GPG-AGENT, gnupg}).
-
-To set up elisp passphrase cache, set
-@code{epa-file-cache-passphrase-for-symmetric-encryption}.
+The EasyPG Assistant, which comes bundled with Emacs, handles
+decryption of encrypted files automatically, see @ref{Top, , Top, epa,
+EasyPG Assistant User's Manual}.  It is an Emacs user interface to
+@acronym{GnuPG, GNU Privacy Guard}, see @ref{Top, , Top, gnupg, Using
+the GNU Privacy Guard}.  To get started with these quickly, see
+@ref{Quick start, , Quick Start, epa, EasyPG Assistant User's Manual}.
 
 @node GNU Free Documentation License
 @appendix GNU Free Documentation License
-- 
2.30.2

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

[Eli Zaretskii]

> Date: Tue, 11 Jul 2023 22:24:58 +0200
> Cc: 64154@debbugs.gnu.org
> From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
> 
> On 2023-07-11  13:02, Eli Zaretskii wrote:
> 
> > Convert the other text to a simple cross-reference to the main manual,
> > and add whatever info is missing from the main manual, if needed.
> 
> Here it is, for convenience together with both previous patches:
> 
> 0001-Add-concept-index-title-case-structure-titles.patch
> 
> Sent in https://debbugs.gnu.org/cgi/bugreport.cgi?bug=64154#71, LGTMed
> by you in #77.
> 
> 0002-Add-basic-usage-information-and-fix-references.patch
> 
> Sent in https://debbugs.gnu.org/cgi/bugreport.cgi?bug=64154#92 as a
> result of your previous review.
> 
> 0003-Replace-duplicate-text-from-epa.texi-by-a-reference.patch
> 
> Hope these are all OK to you.  If so please commit and merge to 
> emacs-29.  I can close this bug, then.

Thanks, installed on the emacs-29 branch.

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

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

On 2023-07-13  09:52, Eli Zaretskii wrote:

> Thanks, installed on the emacs-29 branch.

Thanks, closing this bug.