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.