bug#64154: Some additions to the EasyPG Assistant's manual

[Jens Schmidt]

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?