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" <bug-gnu-emacs@gnu.org>]

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