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

[Eli Zaretskii <eliz@gnu.org>]

> Date: Sat, 8 Jul 2023 22:31:16 +0200
> From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
> Cc: 64154@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@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.