[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#64154: Some additions to the EasyPG Assistant's manual
From: |
Eli Zaretskii |
Subject: |
bug#64154: 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@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.
- bug#64154: Some additions to the EasyPG Assistant's manual, Jens Schmidt, 2023/07/08
- bug#64154: Some additions to the EasyPG Assistant's manual,
Eli Zaretskii <=
- bug#64154: Some additions to the EasyPG Assistant's manual, Jens Schmidt, 2023/07/09
- bug#64154: Some additions to the EasyPG Assistant's manual, Eli Zaretskii, 2023/07/09
- bug#64154: Some additions to the EasyPG Assistant's manual, Jens Schmidt, 2023/07/09
- bug#64154: Some additions to the EasyPG Assistant's manual, Eli Zaretskii, 2023/07/11
- bug#64154: Some additions to the EasyPG Assistant's manual, Jens Schmidt, 2023/07/11
- bug#64154: Some additions to the EasyPG Assistant's manual, Eli Zaretskii, 2023/07/13
- bug#64154: Some additions to the EasyPG Assistant's manual, Jens Schmidt, 2023/07/13