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

Previous Next

Full log

Message #38 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 18:56:20 +0200

[Message part 1 (text/plain, inline)]

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

[0002-Brush-up-index-entries-after-review.patch (text/x-patch, attachment)]

Previous Next

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