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

[Jens Schmidt]

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