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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 64154 in the body.
You can then email your comments to 64154 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

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

From: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
To: bug-gnu-emacs <at> gnu.org
Subject: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi
Date: Sun, 18 Jun 2023 19:29:40 +0200

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

Tags: patch

Attached is a patch with a first draft on some additions to epa.texi.
Eli has reviewed that already, will provide his review comments in the
next update and continue to update this bug as needed.

This is related to bug#63627, where I noticed that some user
documentation in epa.texi would also help better understanding and using
plstore.el.

[epa.texi.patch (text/x-patch, attachment)]

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

From: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
To: 64154 <at> debbugs.gnu.org
Subject: Fwd: Some additions to the EasyPG Assistant's manual
Date: Sun, 18 Jun 2023 19:32:29 +0200

-------- Forwarded Message --------
Subject: Re: Some additions to the EasyPG Assistant's manual
Date: Sat, 17 Jun 2023 10:44:08 +0300
From: Eli Zaretskii <eliz <at> gnu.org>
To: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
CC: emacs-devel <at> gnu.org

> Date: Sun, 11 Jun 2023 20:00:12 +0200
> From: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
> 
> Hi,
> 
> I have been setting up GnuPG for Emacs/EPA lately for transparent file
> encryption and decryption, and done so for the first time.  I've
> condensed my experiences in some additions to the EPA texi file, see 
> attached patch.  Of course, such experiences are highly personal, but at 
> least on Stackoverflow others have been struggling with the same issues 
> as I did ...
> 
> This patch still needs some brushing up, and some splitting up probably
> as well.  It is based on emacs-29.

Please in the future post patches via "M-x report-emacs-bug".

> +You can use EasyPG Assistant without any Emacs or GnuPG configuration
> +whatsoever, for example to encrypt and decrypt files automatically
> +with symmetric encryption, @xref{Encrypting/decrypting gpg files}.
                              ^^^^^
You want "see @ref" here, not @xref.  The latter is only pertinent at
the beginning of a sentence, because it produces a capitalized "See".

> +When you save a buffer, say, to file @file{foo.gpg} for the first
> +time, EasyPG Assistant presents you a list of keys in a new buffer
> +@file{*Keys*} where you can select recipients for encryption.

I don't think "new" is right here: Emacs generally reuses buffers that
already exist.  I'd drop "new" there.

> +@xref{Key management} for a description of the format of that buffer.
                        ^
Comma missing there.  Some old version of Texinfo need it.

> +You can streamline this recipient selection step by customizing
> +variables @code{epa-file-encrypt-to} and @code{epa-file-select-keys},
> +see below.

Instead of "see below", please add a cross-reference to the node where
these variables are documented.

> +If you have created your own keypair <at> footnote{For encryption and
> +decryption of files you do not intend to share you do not have to use
                                                 ^
A comma is missing there.

> +also use some free-form string that gives information on the use of
> +the keypair, like @code{backup} or @code{account database}.} you can
                                                               ^
Another comma missing there.

> +encryption for that file.  Since encryption is performed with your
> +public key, no passphrase is prompted for the buffer save, but you
> +will be prompted for your passphrase for file reads every now and
> +then, depending on the gpg-agent cache configuration.

Passive voice alert!

> +@xref{Caching Passphrases} for more information.
                             ^
Comma after the closing brace is missing.

> +As of June 2023, there are three active branches of GnuPG: 2.4,
> +2.2, and 1.4.  All those branches should work flawlessly with Emacs
>  with basic use-cases.  They have, however, some incompatible
>  characteristics, which might be visible when used from Emacs.

Given the known issues with GnuPG 2.4.1, do we need to say something
about that here?

> +@node GnuPG Pinentry
> +@chapter GnuPG Pinentry

Pleased add an index entry for the subject of this chapter.  In
general, it is a good idea to have an index entry for each
chapter/section/subsection naming is main subject.

> +@enumerate
> +@item Use Emacs only for GnuPG requests that are triggered by Emacs itself,
> +@item use Emacs for all GnuPG requests, or
> +@item use Emacs for all GnuPG requests with other Pinentry as fallback.

The capitalization if these items is inconsistent.

> +FIXME: Brush the following paragraphs up.

??

> +1.: Ensure allow-loopback-pinentry is is configured for the GPG agent,
> +which should be the default.  Configure epg-pinentry-mode to
> +`loopback.
> +
> +2.: Make pinentry-emacs the default pinentry by means of your
> +operating system.  Install package pinentry from GNU ELPA and execute
> +M-x pinentry-start to start the Pinentry service.  All GnuPG
> +passphrase requests should result in a minibuffer prompt in the
> +running Emacs.  If Emacs or pinentry service are not running,
> +passphrase requests fail.
> +
> +3.: Ensure other Pinentry supports Emacs prompt.  pinentry-curses
> +does, for example.  Configure option allow-emacs-pinentry in
> +gpg-agent.conf.  Set environment variable INSIDE_EMACS for the calling
> +process.  Install package pinentry.  Now if Emacs is running and
> +pinentry-start has been exeucted, all GnuPG passphrase requests should
> +result in a minibuffer prompt in the running Emacs.  If Emacs or
> +Pinentry service are not running, GnuPG uses the regular Pinentry
> +instead.
> +
> +First alternative can be configured in addition to onw of the others:
> +Requests triggered from within Emacs (like opening a gpg-encrypted
> +file) are handled through loopback pinentry, Requests outside of emacs
> +through pinentry feature.
> +
> +Note that the selection of a concrete Pinentry program determines only
> +@emph{how} GnuPG queries for passphrases and not @emph{how often}.
> +For the latter question @xref{Caching Passphrases}.

This doesn't seem to be finalized?

> +need to re-enter the passphrase occasionally.  However, the
> +configuration is a bit confusing since it depends on your GnuPG
> +installation @xref{GnuPG version compatibility}, encryption method
                ^^^^^
Here, a @pxref in parentheses is TRT.

Thanks.

Message #11 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: Thu, 29 Jun 2023 23:10:41 +0200

On 2023-06-18  19:32, Eli Zaretskii wrote:

Back from greener pastures, sorry for the delay.

>> +@node GnuPG Pinentry
>> +@chapter GnuPG Pinentry
> 
> Pleased add an index entry for the subject of this chapter.  In 
> general, it is a good idea to have an index entry for each 
> chapter/section/subsection naming is main subject.

Problem here being that epa.texi has no concept index yet.  Should I
create one from the existing chapters/sections/subsections in a separate
patch?

And the next question is: Does this ("new documentation of existing 
features") qualify for Emacs 29?

Thanks

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
Cc: 64154 <at> debbugs.gnu.org
Subject: Re: 29.0.92; Provide additional details on GnuPG and EPA usage in
 epa.texi
Date: Fri, 30 Jun 2023 08:54:06 +0300

> Date: Thu, 29 Jun 2023 23:10:41 +0200
> From: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
> Cc: 64154 <at> debbugs.gnu.org
> 
> On 2023-06-18  19:32, Eli Zaretskii wrote:
> 
> Back from greener pastures, sorry for the delay.
> 
> >> +@node GnuPG Pinentry
> >> +@chapter GnuPG Pinentry
> > 
> > Pleased add an index entry for the subject of this chapter.  In 
> > general, it is a good idea to have an index entry for each 
> > chapter/section/subsection naming is main subject.
> 
> Problem here being that epa.texi has no concept index yet.  Should I
> create one from the existing chapters/sections/subsections in a separate
> patch?

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.

> And the next question is: Does this ("new documentation of existing 
> features") qualify for Emacs 29?

Documentation improvements and fixes are always okay on the release
branch.  (But please hurry, since I plan on releasing Emacs 29.1 soon,
barring any grave bugs that will be uncovered.)

Thanks.

Message #17 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: Fri, 30 Jun 2023 21:13:40 +0200

On 2023-06-30  07:54, Eli Zaretskii wrote:

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

Another such possible systematic update I could do while touching 
things: Consistently title-casing node names and/or chapter/section 
titles.  OK or not OK?  I'm not sure about external references if case 
changes.

Thanks

Message #20 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: Fri, 30 Jun 2023 21:32:27 +0200

On 2023-06-30  21:13, Jens Schmidt wrote:
> On 2023-06-30  07:54, Eli Zaretskii wrote:
> 
>> 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.
> 
> Another such possible systematic update I could do while touching 
> things: Consistently title-casing node names and/or chapter/section 
> titles.  OK or not OK?  I'm not sure about external references if case 
> changes.

Just found this in the texinfo manual:

   * Case is significant in node names.

Will keep the node names untouched, but title-case the hierarchy.

Message #23 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: Fri, 30 Jun 2023 22:54:11 +0200

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

On 2023-06-30  07:54, Eli Zaretskii wrote:

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

[0001-Add-concept-index-title-case-structure-titles.patch (text/x-patch, attachment)]

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

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

> Date: Fri, 30 Jun 2023 21:13:40 +0200
> Cc: 64154 <at> debbugs.gnu.org
> From: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
> 
> On 2023-06-30  07:54, Eli Zaretskii wrote:
> 
> > 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.
> 
> Another such possible systematic update I could do while touching 
> things: Consistently title-casing node names and/or chapter/section 
> titles.  OK or not OK?  I'm not sure about external references if case 
> changes.

Chapters and sections should be capitalized according to the rules of
English.  Node names I'd leave a lone: there's no capitalization
convention about them.

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

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

> Date: Fri, 30 Jun 2023 22:54:11 +0200
> From: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
> Cc: 64154 <at> 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.

Message #32 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 13:13:44 +0200

On 2023-07-01  08:01, Eli Zaretskii wrote:

> Thanks, see some comments below.

Thanks for your review.  Comments and new patch to follow, only I have a
more general question now:

How would you prefer my follow-up changes?  On top of the first patch
(so you can more easily check where I followed your recommendations and
where not) or should I rebase both commits from origin/emacs-29 into one
patch?

Another more general question: You have been asking for a hurry since
you'd like to release Emacs 29.1.  What would happen to patches coming
after that release?

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

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

> Date: Sat, 1 Jul 2023 13:13:44 +0200
> Cc: 64154 <at> debbugs.gnu.org
> From: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
> 
> How would you prefer my follow-up changes?  On top of the first patch
> (so you can more easily check where I followed your recommendations and
> where not) or should I rebase both commits from origin/emacs-29 into one
> patch?

No, on top of the current branch.

> Another more general question: You have been asking for a hurry since
> you'd like to release Emacs 29.1.  What would happen to patches coming
> after that release?

They will go into Emacs 29.2.

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)]

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

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

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

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

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

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

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

> Date: Sat, 1 Jul 2023 19:56:08 +0200
> Cc: 64154 <at> debbugs.gnu.org
> From: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
> 
>    @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?

They are not redundant, since they all start differently.  But I would
suggest to consider the first one for removal.

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

The alphabetic order of the index in the printed versions exists to
help finding the index entries.  People still first think about what
they want to find, and only then look it up.

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

The former.

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

The Texinfo manual doesn't need to be changed.  It's a very good
manual.  As for "no rules", the most important rule for index entries
is that they should fit what people have in mind when they look for
the subject.  All the rest are corollaries and gray hair gained by
experience.

Message #50 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 22:20:12 +0200

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

On 2023-07-01  20:49, Eli Zaretskii wrote:

Attached a third patch - please review 2nd and 3rd combined against 1st.

>>     @cindex GnuPG version compatibility
>>     @cindex version compatibility with GnuPG
>>     @cindex compatibility with GnuPG
> 
> They are not redundant, since they all start differently.  But I would
> suggest to consider the first one for removal.

Why, then?  I can imagine using that as index search, for example if I
remember that the section is named like that.  Plus it does not seem to
break completion.

> The Texinfo manual doesn't need to be changed.  It's a very good
> manual.  [...]

At least w.r.t. to capitalization you both seem to fundamentally
disagree (quotes from "Index Entries(texinfo)"):

  [...] capitalizing only proper
  names and acronyms that always call for uppercase letters.
  This is the case convention we use in most GNU manuals'
  indices.

OTOH here you completely agree:

  Like typesetting, the construction of an index is a skilled
  art, the subtleties of which may not be appreciated until you
  need to do it yourself.

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

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

From: Richard Stallman <rms <at> gnu.org>
To: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
Cc: eliz <at> gnu.org, 64154 <at> debbugs.gnu.org
Subject: Re: bug#64154: 29.0.92;
 Provide additional details on GnuPG and EPA usage in epa.texi
Date: Sat, 01 Jul 2023 22:15:45 -0400

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Problem here being that epa.texi has no concept index yet.  Should I
  > create one from the existing chapters/sections/subsections in a separate
  > patch?

It would be good to make a concept index, but please index all the
concepts mentioned -- not just the ones that are names of secxtions.

If you look at @cindex commands in the Emacs manual, which has a very
thorough concept index, you'll see that there are @cindex commands for
many concepts which do not appear in section titles.  This is the way
to do a complete job.  Please do a complete job for EPA too!

If you search for @cindex in the Emacs manual sources, you can see
this quickly.  Looking through 20% of the manual should be enough to
give you the picture.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
Cc: 64154 <at> debbugs.gnu.org
Subject: Re: 29.0.92; Provide additional details on GnuPG and EPA usage in
 epa.texi
Date: Sun, 02 Jul 2023 07:59:15 +0300

> Date: Sat, 1 Jul 2023 22:20:12 +0200
> Cc: 64154 <at> debbugs.gnu.org
> From: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
> 
> >>     @cindex GnuPG version compatibility
> >>     @cindex version compatibility with GnuPG
> >>     @cindex compatibility with GnuPG
> > 
> > They are not redundant, since they all start differently.  But I would
> > suggest to consider the first one for removal.
> 
> Why, then?

Because people are very unlikely to think about "GnuPG version
compatibility".  They are likely to think about "version
compatibility" and perhaps just "compatibility".  Just put yourself
into the shoes of such a reader, and ask yourself what would you type
at Info-index's prompt.

> I can imagine using that as index search, for example if I remember
> that the section is named like that.  Plus it does not seem to break
> completion.

If you remember the name of the section, you can usually use 'g',
since node names are usually very similar to section names.

> > The Texinfo manual doesn't need to be changed.  It's a very good
> > manual.  [...]
> 
> At least w.r.t. to capitalization you both seem to fundamentally
> disagree (quotes from "Index Entries(texinfo)"):
> 
>    [...] capitalizing only proper
>    names and acronyms that always call for uppercase letters.
>    This is the case convention we use in most GNU manuals'
>    indices.

My personal rule is to use capital letters in index entries only when
absolutely necessary.  It is not necessary with "gpg" or "gnupg".  The
above citation says something similar.

> Attached a third patch - please review 2nd and 3rd combined against 1st.

Does it mean the patch you sent is just part of the changes?

Message #59 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: Sun, 2 Jul 2023 09:13:25 +0200

On 2023-07-02  06:59, Eli Zaretskii wrote:

> Because people are very unlikely to think about "GnuPG version 
> compatibility".  They are likely to think about "version 
> compatibility" and perhaps just "compatibility".  Just put yourself 
> into the shoes of such a reader, and ask yourself what would you
> type at Info-index's prompt.

But after all, I *am* such a reader.  And I would type that, because "i"
is my main entry point to Info manuals, not "g".

My question here really is: Why would it be bad to have that additional
index entry?  It does not break completion, it is not overly generic, it
is just ... there, ready for some less likely reader to search for it.

(Spoiler: *That* one entry is still in, even in my latest patch.  I
understood your comment:

>>> They are not redundant, since they all start differently.  But I 
>>> would suggest to consider the first one for removal.

to mean that removal is recommended but optional.  Please let me know if
you meant otherwise.)

>> At least w.r.t. to capitalization you both seem to fundamentally 
>> disagree (quotes from "Index Entries(texinfo)"):
>> 
>> [...] capitalizing only proper names and acronyms that always call
>> for uppercase letters. This is the case convention we use in most
>> GNU manuals' indices.
> 
> My personal rule is to use capital letters in index entries only
> when absolutely necessary.  It is not necessary with "gpg" or
> "gnupg".  The above citation says something similar.

I would have considered "EasyPG Assistant" a proper name and the "GNU"
in "GNU Privacy Guard" an acronym, but anyway ...

>> Attached a third patch - please review 2nd and 3rd combined against
>> 1st.
> 
> Does it mean the patch you sent is just part of the changes?

Yes, it is.  It undoes some of the changes of the previous patch.

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

From: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
To: rms <at> gnu.org
Cc: eliz <at> gnu.org, 64154 <at> debbugs.gnu.org
Subject: Re: bug#64154: 29.0.92; Provide additional details on GnuPG and EPA
 usage in epa.texi
Date: Sun, 2 Jul 2023 09:34:46 +0200

On 2023-07-02  04:15, Richard Stallman wrote:

>> Problem here being that epa.texi has no concept index yet.  Should I
>> create one from the existing chapters/sections/subsections in a separate
>> patch?
> 
> It would be good to make a concept index, but please index all the
> concepts mentioned -- not just the ones that are names of secxtions.

I was initially hoping for the better-than-nothing half of Dick's quote 
from the Texinfo manual:

  Documentation is like sex: when it is good, it is very, very good;
  and when it is bad, it is better than nothing.  --Dick Brandon

But Eli is already trying hard to direct me otherwise, thanks.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
Cc: 64154 <at> debbugs.gnu.org
Subject: Re: 29.0.92; Provide additional details on GnuPG and EPA usage in
 epa.texi
Date: Sun, 02 Jul 2023 11:18:49 +0300

> Date: Sun, 2 Jul 2023 09:13:25 +0200
> Cc: 64154 <at> debbugs.gnu.org
> From: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
> 
> On 2023-07-02  06:59, Eli Zaretskii wrote:
> 
> > Because people are very unlikely to think about "GnuPG version 
> > compatibility".  They are likely to think about "version 
> > compatibility" and perhaps just "compatibility".  Just put yourself 
> > into the shoes of such a reader, and ask yourself what would you
> > type at Info-index's prompt.
> 
> But after all, I *am* such a reader.  And I would type that, because "i"
> is my main entry point to Info manuals, not "g".

Then go for it!

> My question here really is: Why would it be bad to have that additional
> index entry?

I said "I'd consider that for removal", that's all.  If you considered
it and decided to leave it, fine.  It's a judgment call.

> >> Attached a third patch - please review 2nd and 3rd combined against
> >> 1st.
> > 
> > Does it mean the patch you sent is just part of the changes?
> 
> Yes, it is.  It undoes some of the changes of the previous patch.

Can you send a single patch with all the changes, please?

Message #68 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: Sun, 2 Jul 2023 13:54:16 +0200

On 2023-07-02  10:18, Eli Zaretskii wrote:

> Can you send a single patch with all the changes, please?

Ok, next general question, probably I have misunderstood your previous 
comment on that.  git lingo is still somewhat new to me...

Suppose I provide a patch P1 on emacs-29 and you review P1.  How should 
I provide the changes CH resulting from that review?  With a patch P2 
like this (A):

  emacs-29 -> P1 -> P2

Or with a patch P1' merging P1 and P2 like this (B):

  emacs-29 -> P1'

Or does it depend on the changes CH and you decide case-by-case (C)?

Message #71 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: Sun, 2 Jul 2023 13:55:08 +0200

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

On 2023-07-02  10:18, Eli Zaretskii wrote:

> Can you send a single patch with all the changes, please?

Here you go.

Thanks

[0001-Add-concept-index-title-case-structure-titles.patch (text/x-patch, attachment)]

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
Cc: 64154 <at> debbugs.gnu.org
Subject: Re: 29.0.92; Provide additional details on GnuPG and EPA usage in
 epa.texi
Date: Sun, 02 Jul 2023 15:16:04 +0300

> Date: Sun, 2 Jul 2023 13:54:16 +0200
> Cc: 64154 <at> debbugs.gnu.org
> From: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
> 
> On 2023-07-02  10:18, Eli Zaretskii wrote:
> 
> > Can you send a single patch with all the changes, please?
> 
> Ok, next general question, probably I have misunderstood your previous 
> comment on that.  git lingo is still somewhat new to me...
> 
> Suppose I provide a patch P1 on emacs-29 and you review P1.  How should 
> I provide the changes CH resulting from that review?  With a patch P2 
> like this (A):
> 
>    emacs-29 -> P1 -> P2
> 
> Or with a patch P1' merging P1 and P2 like this (B):
> 
>    emacs-29 -> P1'
> 
> Or does it depend on the changes CH and you decide case-by-case (C)?

I usually prefer to see a single patch relative to the current Git,
even in subsequent reviews.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
Cc: 64154 <at> debbugs.gnu.org
Subject: Re: 29.0.92; Provide additional details on GnuPG and EPA usage in
 epa.texi
Date: Sun, 02 Jul 2023 15:18:01 +0300

> Date: Sun, 2 Jul 2023 13:55:08 +0200
> Cc: 64154 <at> debbugs.gnu.org
> From: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
> 
> > Can you send a single patch with all the changes, please?
> 
> Here you go.

Thanks, this LGTM.

Message #80 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: Some additions to the EasyPG Assistant's manual
Date: Sat, 8 Jul 2023 22:31:16 +0200

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

So after setting up the concept index, here comes what I originally
intended to add to epa.texi.  Plus my comments on you first review
(https://debbugs.gnu.org/cgi/bugreport.cgi?bug=64154#8) where I have
additional questions.  Unless otherwise stated I followed your
recommendations, however.

On 2023-06-17  09:44, Eli Zaretskii wrote:

>> +You can use EasyPG Assistant without any Emacs or GnuPG configuration
>> +whatsoever, for example to encrypt and decrypt files automatically
>> +with symmetric encryption, @xref{Encrypting/decrypting gpg files}.
>                                ^^^^^
> You want "see @ref" here, not @xref.  The latter is only pertinent at
> the beginning of a sentence, because it produces a capitalized "See".

Understood.  Actually, I copied the habit of the original authors there.
I fixed my own inappropriate @xrefs plus theirs.

>> +@xref{Key management} for a description of the format of that
>> buffer.
>                        ^
> Comma missing there.  Some old version of Texinfo need it.

I changed these as you have proposed.  But TBH I find that comma rather
disturbing.  This might be a non-native speaker's view, but isn't then

  "See @ref{Key management} for a description ...

easier to read *and* clearer in the texi file?  Or, IOW, do we *have* to
use @xref at the beginning of sentences because it has some other nice
properties?  Same question for @pxref?

>> +You can streamline this recipient selection step by customizing
>> +variables @code{epa-file-encrypt-to} and @code{epa-file-select-keys},
>> +see below.
> 
> Instead of "see below", please add a cross-reference to the node where
> these variables are documented.

Actually, here "see below" refers to the same node.  I use now "...
described further below in this section" to clarify that.

>> +As of June 2023, there are three active branches of GnuPG: 2.4,
>> +2.2, and 1.4.  All those branches should work flawlessly with Emacs
>>   with basic use-cases.  They have, however, some incompatible
>>   characteristics, which might be visible when used from Emacs.
> 
> Given the known issues with GnuPG 2.4.1, do we need to say something
> about that here?

Done that.

Finally, I noticed that node "GnuPG and EasyPG Assistant
Configuration(auth)" duplicates some of the information in section
"Caching Passphrases(epa)", which means that these will be out of sync
as soon as my changes have landed.  WDYT about that?

[0002-Add-basic-usage-information-and-fix-references.patch (text/x-patch, attachment)]

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
Cc: 64154 <at> debbugs.gnu.org
Subject: Re: Some additions to the EasyPG Assistant's manual
Date: Sun, 09 Jul 2023 10:24:37 +0300

> Date: Sat, 8 Jul 2023 22:31:16 +0200
> From: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
> Cc: 64154 <at> debbugs.gnu.org
> 
> So after setting up the concept index, here comes what I originally
> intended to add to epa.texi.  Plus my comments on you first review
> (https://debbugs.gnu.org/cgi/bugreport.cgi?bug=64154#8) where I have
> additional questions.  Unless otherwise stated I followed your
> recommendations, however.

Thanks.

> >> +@xref{Key management} for a description of the format of that
> >> buffer.
> >                        ^
> > Comma missing there.  Some old version of Texinfo need it.
> 
> I changed these as you have proposed.  But TBH I find that comma rather
> disturbing.  This might be a non-native speaker's view, but isn't then
> 
>    "See @ref{Key management} for a description ...
> 
> easier to read *and* clearer in the texi file?  Or, IOW, do we *have* to
> use @xref at the beginning of sentences because it has some other nice
> properties?

It doesn't matter whether you use @xref or @ref, they both should be
followed by some punctuation, either a comma or a period, if we want
to support those older versions of Texinfo which insisted on that.

> Same question for @pxref?

@pxref is different, in that it doesn't need such punctuation.  Which
is why it is pertinent only in some contexts.

> >> +You can streamline this recipient selection step by customizing
> >> +variables @code{epa-file-encrypt-to} and @code{epa-file-select-keys},
> >> +see below.
> > 
> > Instead of "see below", please add a cross-reference to the node where
> > these variables are documented.
> 
> Actually, here "see below" refers to the same node.

Then disregard my comment, I was under the impression that you refer
to a different node.

> +John Michael Ashley's GNU Privacy Handbook, available online as part
> +of @uref{https://gnupg.org/documentation/guides.html, the GnuPG user
> +guides}, provides an introduction to GnuPG use and configuration.  In
> +contrast to that, the GnuPG manual (@pxref{Top, , Top, gnupg, Using
> +the GNU Privacy Guard}) is more of of a reference manual.
                                   ^^^^^
Redundant "of" there.

> +When you save a buffer, say, to file @file{foo.gpg} for the first
> +time, EasyPG Assistant presents you a list of keys in a buffer

The reference to the file's name here is not necessary, and just makes
the text harder to read.  This simpler variant doesn't seem to lose
any useful content:

  When you save a buffer to an encrypted file for the first time,
  EasyPG Assistant presents you a list of keys in a buffer ...

> +reads, since the gpg-agent caches your passphrase for file reads at
> +least for some time, but not for buffer saves.

I think gpg-agent should be in @command (here and elsewhere), since
it's a shell command name.

Also, perhaps a cross-reference to the GPG documentation that
describes gpg-agent would be appropriate here?

> +@cindex public key encryption, passphrase entry for
> +If you have created your own keypair <at> footnote{For encryption and
> +decryption of files you do not intend to share, you do not have to use
> +an email address as recipient during creation of the keypair.  You can
> +also use some free-form string that gives information on the use of
> +the keypair, like @code{backup} or @code{account database}.}, you can
> +select that as recipient, and EasyPG Assistant uses public key
> +encryption for that file.                      ^^^^

Probably "will use" there is better?

> +@cindex tempory files created by easypg assistant
> +To encrypt and decrypt files as described above EasyPG Assistant under
> +certain circumstances uses intermediate tempory files that contain the
> +plain-text contents of the files it processes.  EasyPG Assistant
> +creates them below the directory returned by function
> +@code{temporary-file-directory}.

I think a cross-reference to the place in ELisp manual, where
temporary-file-directory is described, will be useful here.

>  For frequently visited files, it might be a good idea to tell Emacs
> -which encryption method should be used through @xref{File Variables, ,
> -, emacs, the Emacs Manual}.  Use the @code{epa-file-encrypt-to} local
> -variable for this.
> +which encryption method should be used through file variables
> +(@pxref{File Variables, , Local Variables in Files, emacs, The Emacs
> +Editor}).  Use the @code{epa-file-encrypt-to} local variable for this.
>  @vindex epa-file-encrypt-to

This @vindex entry should be before the text describing the variable,
not after it.

> @@ -478,6 +532,11 @@ Encrypting/decrypting gpg files
>  @defvar epa-file-cache-passphrase-for-symmetric-encryption
>  If non-@code{nil}, cache passphrase for symmetric encryption.  The
>  default value is @code{nil}.
> +
> +For security reasons, this option is turned off by default and not
> +recommended to use.
   ^^^^^^^^^^^^^^^^^^
Either "not recommended for use" or "not recommended to be used".

> +@cindex loopback pinentry
> +This so called loopback Pinentry has the added benefit that it works

This introduces terminology, so it should use @dfn:

  This so-called @dfn{loopback Pinentry} has the added benefit ...

> +also when you use Emacs remotely or from a text-only terminal.  To
> +enable it:
> +
> +@enumerate
> +@item
> +Ensure that option @code{allow-loopback-pinentry} is configured for
> +gpg-agent, which should be the default.
> +
> +@item
> +Customize variable @code{epg-pinentry-mode} to @code{loopback} in
> +Emacs.
> +@end enumerate

Shouldn't the two variables mentioned here be indexed?  If they are
already indexed, but the index entries point to another place, having
a cross-reference here to that place is TRT.

> +@c In case somebody requests these:

It is better to use @ignore...@end ignore instead of commenting out.

> +@c Make pinentry-emacs the default Pinentry by means of your operating
> +@c system.  Install package pinentry.el from GNU ELPA and execute M-x
> +@c pinentry-start to start the Emacs Pinentry service.  *All* GnuPG

"M-x command" should be in @kbd.

Message #86 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: Some additions to the EasyPG Assistant's manual
Date: Sun, 9 Jul 2023 12:18:39 +0200

On 2023-07-09  09:24, Eli Zaretskii wrote:

Thanks for your thorough review.  Some follow-up comments and questions:

> The reference to the file's name here is not necessary, and just makes
> the text harder to read.  This simpler variant doesn't seem to lose
> any useful content:
> 
>    When you save a buffer to an encrypted file for the first time,
>    EasyPG Assistant presents you a list of keys in a buffer ...
> 
>> +reads, since the gpg-agent caches your passphrase for file reads at
>> +least for some time, but not for buffer saves.
> 
> I think gpg-agent should be in @command (here and elsewhere), since
> it's a shell command name.

Yet another case where I tried to maintain consistency with the original
manual: It uses gpg-agent rather consistently (without @command) where I
probably would have used the proper name "GnuPG agent".

In any case it means changing existing text, not simply adding new text ...

>>   For frequently visited files, it might be a good idea to tell Emacs
>> -which encryption method should be used through @xref{File Variables, ,
>> -, emacs, the Emacs Manual}.  Use the @code{epa-file-encrypt-to} local
>> -variable for this.
>> +which encryption method should be used through file variables
>> +(@pxref{File Variables, , Local Variables in Files, emacs, The Emacs
>> +Editor}).  Use the @code{epa-file-encrypt-to} local variable for this.
>>   @vindex epa-file-encrypt-to
> 
> This @vindex entry should be before the text describing the variable,
> not after it.

... and same here.

My real problem here is to fix minor issues present in the existing text
and add my own changes in one commit, but you seem to be more relaxed
here, so I will just do that.

>> +also when you use Emacs remotely or from a text-only terminal.  To
>> +enable it:
>> +
>> +@enumerate
>> +@item
>> +Ensure that option @code{allow-loopback-pinentry} is configured for
>> +gpg-agent, which should be the default.
>> +
>> +@item
>> +Customize variable @code{epg-pinentry-mode} to @code{loopback} in
>> +Emacs.
>> +@end enumerate
>
> Shouldn't the two variables mentioned here be indexed?  If they are
> already indexed, but the index entries point to another place, having
> a cross-reference here to that place is TRT.

I thought that @vindex is somewhat reserved for Emacs variables that are
defined with @defvar.  So the variable index is more of an index for
everything "variable-like"?

>> +@c Make pinentry-emacs the default Pinentry by means of your operating
>> +@c system.  Install package pinentry.el from GNU ELPA and execute M-x
>> +@c pinentry-start to start the Emacs Pinentry service.  *All* GnuPG
> 
> "M-x command" should be in @kbd.

Even if the whole text is a comment or to be @ignored?  In that case
should I probably also use @command{pinentry-emacs}, @file{pinentry.el},
etc. in the quoted paragraph?

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
Cc: 64154 <at> debbugs.gnu.org
Subject: Re: Some additions to the EasyPG Assistant's manual
Date: Sun, 09 Jul 2023 14:26:46 +0300

> Date: Sun, 9 Jul 2023 12:18:39 +0200
> Cc: 64154 <at> debbugs.gnu.org
> From: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
> 
> >> +reads, since the gpg-agent caches your passphrase for file reads at
> >> +least for some time, but not for buffer saves.
> > 
> > I think gpg-agent should be in @command (here and elsewhere), since
> > it's a shell command name.
> 
> Yet another case where I tried to maintain consistency with the original
> manual: It uses gpg-agent rather consistently (without @command) where I
> probably would have used the proper name "GnuPG agent".
> 
> In any case it means changing existing text, not simply adding new text ...

There's no need to fix everything (although you get bonus points for
doing so), it is enough not to add such problems in new text.

> I thought that @vindex is somewhat reserved for Emacs variables that are
> defined with @defvar.  So the variable index is more of an index for
> everything "variable-like"?

No, @vindex is for any variables.  (@defvar produces an index entry
automatically, so you don't have to add a @vindex.)

> >> +@c Make pinentry-emacs the default Pinentry by means of your operating
> >> +@c system.  Install package pinentry.el from GNU ELPA and execute M-x
> >> +@c pinentry-start to start the Emacs Pinentry service.  *All* GnuPG
> > 
> > "M-x command" should be in @kbd.
> 
> Even if the whole text is a comment or to be @ignored?

Well, if we want this text to be usable at some future point, yes.
Otherwise, why keep it?  And it isn't like making it right needs too
much work, so I think it's worth our while.

Message #92 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: Some additions to the EasyPG Assistant's manual
Date: Sun, 9 Jul 2023 16:41:05 +0200

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

On 2023-07-09  13:26, Eli Zaretskii wrote:

> There's no need to fix everything (although you get bonus points for
> doing so), it is enough not to add such problems in new text.

Turned out that most references were mine, anyway, so little bonus.  I 
changed them to "GnuPG Agent" where the "abstract agent" more likely is 
being referred to and to @command{gpg-agent} where the "concrete 
command" is meant.  (The GnuPG manual is, um, extremely inconsistent in 
naming this thing, so nothing to be learnt from it.)

Other than that I followed your proposals, new patch attached.

There is this one open question regarding a completely different manual 
("Emacs auth-source") from one of my previous mails, though:

> Finally, I noticed that section "GnuPG and EasyPG Assistant
> Configuration(auth)" duplicates some of the information in section
> "Caching Passphrases(epa)", which means that these will be out of sync
> as soon as my changes have landed.  WDYT about that?

[0002-Add-basic-usage-information-and-fix-references.patch (text/x-patch, attachment)]

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
Cc: 64154 <at> debbugs.gnu.org
Subject: Re: Some additions to the EasyPG Assistant's manual
Date: Tue, 11 Jul 2023 14:02:14 +0300

> Date: Sun, 9 Jul 2023 16:41:05 +0200
> From: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
> Cc: 64154 <at> debbugs.gnu.org
> 
> There is this one open question regarding a completely different manual 
> ("Emacs auth-source") from one of my previous mails, though:
> 
> > Finally, I noticed that section "GnuPG and EasyPG Assistant
> > Configuration(auth)" duplicates some of the information in section
> > "Caching Passphrases(epa)", which means that these will be out of sync
> > as soon as my changes have landed.  WDYT about that?

Convert the other text to a simple cross-reference to the main manual,
and add whatever info is missing from the main manual, if needed.

Thanks.

Message #98 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: Some additions to the EasyPG Assistant's manual
Date: Tue, 11 Jul 2023 22:24:58 +0200

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

On 2023-07-11  13:02, Eli Zaretskii wrote:

> Convert the other text to a simple cross-reference to the main manual,
> and add whatever info is missing from the main manual, if needed.

Here it is, for convenience together with both previous patches:

0001-Add-concept-index-title-case-structure-titles.patch

Sent in https://debbugs.gnu.org/cgi/bugreport.cgi?bug=64154#71, LGTMed
by you in #77.

0002-Add-basic-usage-information-and-fix-references.patch

Sent in https://debbugs.gnu.org/cgi/bugreport.cgi?bug=64154#92 as a
result of your previous review.

0003-Replace-duplicate-text-from-epa.texi-by-a-reference.patch

Hope these are all OK to you.  If so please commit and merge to 
emacs-29.  I can close this bug, then.

Thanks

[0001-Add-concept-index-title-case-structure-titles.patch (text/x-patch, attachment)]

[0002-Add-basic-usage-information-and-fix-references.patch (text/x-patch, attachment)]

[0003-Replace-duplicate-text-from-epa.texi-by-a-reference.patch (text/x-patch, attachment)]

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
Cc: 64154 <at> debbugs.gnu.org
Subject: Re: Some additions to the EasyPG Assistant's manual
Date: Thu, 13 Jul 2023 10:52:44 +0300

> Date: Tue, 11 Jul 2023 22:24:58 +0200
> Cc: 64154 <at> debbugs.gnu.org
> From: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
> 
> On 2023-07-11  13:02, Eli Zaretskii wrote:
> 
> > Convert the other text to a simple cross-reference to the main manual,
> > and add whatever info is missing from the main manual, if needed.
> 
> Here it is, for convenience together with both previous patches:
> 
> 0001-Add-concept-index-title-case-structure-titles.patch
> 
> Sent in https://debbugs.gnu.org/cgi/bugreport.cgi?bug=64154#71, LGTMed
> by you in #77.
> 
> 0002-Add-basic-usage-information-and-fix-references.patch
> 
> Sent in https://debbugs.gnu.org/cgi/bugreport.cgi?bug=64154#92 as a
> result of your previous review.
> 
> 0003-Replace-duplicate-text-from-epa.texi-by-a-reference.patch
> 
> Hope these are all OK to you.  If so please commit and merge to 
> emacs-29.  I can close this bug, then.

Thanks, installed on the emacs-29 branch.

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

From: Jens Schmidt <jschmidt4gnu <at> vodafonemail.de>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 64154-done <at> debbugs.gnu.org
Subject: Re: Some additions to the EasyPG Assistant's manual
Date: Thu, 13 Jul 2023 20:46:57 +0200

On 2023-07-13  09:52, Eli Zaretskii wrote:

> Thanks, installed on the emacs-29 branch.

Thanks, closing this bug.

Previous Next

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