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.