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

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: 356 bytes --]

Tags: patch

Attached is a patch with a first draft on some additions to epa.texi.
Eli has reviewed that already, will provide his review comments in the
next update and continue to update this bug as needed.

This is related to bug#63627, where I noticed that some user
documentation in epa.texi would also help better understanding and using
plstore.el.

[-- Attachment #2: epa.texi.patch --]
[-- Type: text/x-patch, Size: 7914 bytes --]

diff --git a/doc/misc/epa.texi b/doc/misc/epa.texi
index 6f63a3d7ba0..f416e9eb667 100644
--- a/doc/misc/epa.texi
+++ b/doc/misc/epa.texi
@@ -61,6 +61,7 @@ Top
 * Quick start::
 * Commands::
 * GnuPG version compatibility::
+* GnuPG Pinentry::
 * Caching Passphrases::
 * Bug Reports::
 * GNU Free Documentation License::  The license for this documentation.
@@ -72,7 +73,8 @@ Top
 @node Overview
 @chapter Overview
 
-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.
@@ -86,6 +88,16 @@ Overview
 @node Quick start
 @chapter Quick start
 
+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}.
+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 @url{https://gnupg.org/documentation/guides.html, the GnuPG user
+guides}, provides an introduction to GnuPG use and configuration.
+
 EasyPG Assistant commands are prefixed by @samp{epa-}.  For example,
 
 @itemize @bullet
@@ -368,6 +380,39 @@ 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 new 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},
+see below.
+
+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.
+
+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 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.
+
+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 to be encrypted or decrypted.  It
+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}.
 
@@ -436,6 +481,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
@@ -461,8 +511,8 @@ Querying a key server
 @node GnuPG version compatibility
 @chapter GnuPG version 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
+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.
 
@@ -490,17 +540,71 @@ GnuPG version compatibility
 graphical prompt.
 @end itemize
 
+
+@node GnuPG Pinentry
+@chapter GnuPG Pinentry
+
+An important component of the GnuPG suite is the Pinentry, which
+allows for secure entry of passphrases requests by GnuPG.  GnuPG
+delivers various different programs as Pinentry, ranging from bland
+TTY-only @samp{pinentry-tty} to fancy graphical dialogues for various
+desktop environments, like @samp{pinentry-gnome3}.  Your operating
+system usually determines which of these is used by default.
+
+With some configuration Emacs can also play the role of a Pinentry.
+There are three different scenarios possible@footnote{Not all
+operating systems and distributions support all of the above
+scenarios.  As of June 2023 Debian GNU/Linux, for example, supports
+only the first of them due to security concerns.}:
+
+@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.
+@end enumerate
+
+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}.
+
 @node Caching Passphrases
 @chapter 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
+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 (which is mandatory for GnuPG 2.0 and later).  Here are some
 questions:
 
 @enumerate

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

[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

[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

[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

[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: 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

[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: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

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