GNU bug report logs - #64154
29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi

Previous Next

Full log

Message #44 received at 64154 <at> debbugs.gnu.org (full text, mbox):

From: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 64154 <at> debbugs.gnu.org
Subject: Re: 29.0.92; Provide additional details on GnuPG and EPA usage in
 epa.texi
Date: Sat, 1 Jul 2023 19:56:08 +0200

On 2023-07-01  19:19, Eli Zaretskii wrote:
>> Date: Sat, 1 Jul 2023 18:56:20 +0200 Cc: 64154 <at> debbugs.gnu.org 
>> From: Jens Schmidt <jschmidt4gnu <at> 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 ...

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.