* bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi
@ 2023-06-18 17:29 Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
0 siblings, 0 replies; 24+ messages in thread
From: Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2023-06-18 17:29 UTC (permalink / raw)
To: 64154
[-- Attachment #1: Type: text/plain, Size: 356 bytes --]
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.
[-- Attachment #2: epa.texi.patch --]
[-- Type: text/x-patch, Size: 7914 bytes --]
diff --git a/doc/misc/epa.texi b/doc/misc/epa.texi
index 6f63a3d7ba0..f416e9eb667 100644
--- a/doc/misc/epa.texi
+++ b/doc/misc/epa.texi
@@ -61,6 +61,7 @@ Top
* Quick start::
* Commands::
* GnuPG version compatibility::
+* GnuPG Pinentry::
* Caching Passphrases::
* Bug Reports::
* GNU Free Documentation License:: The license for this documentation.
@@ -72,7 +73,8 @@ Top
@node Overview
@chapter Overview
-EasyPG Assistant provides the following features.
+EasyPG Assistant is an Emacs frontend application to @acronym{GnuPG,
+GNU Privacy Guard} that provides the following features:
@itemize @bullet
@item Key management.
@@ -86,6 +88,16 @@ Overview
@node Quick start
@chapter Quick start
+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}.
+However, to use the full set of EasyPG Assistant's functions you
+should have at least some minimum GnuPG configuration in place.
+
+John Michael Ashley's GNU Privacy Handbook, available online as part
+of @url{https://gnupg.org/documentation/guides.html, the GnuPG user
+guides}, provides an introduction to GnuPG use and configuration.
+
EasyPG Assistant commands are prefixed by @samp{epa-}. For example,
@itemize @bullet
@@ -368,6 +380,39 @@ Encrypting/decrypting gpg files
Similarly, when you save the buffer to a @file{foo.gpg} file,
encrypted data is written.
+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.
+@xref{Key management} for a description of the format of that buffer.
+You can streamline this recipient selection step by customizing
+variables @code{epa-file-encrypt-to} and @code{epa-file-select-keys},
+see below.
+
+If you do not select any recipient during this step, EasyPG Assistant
+uses symmetric encryption. As a consequence, you have to enter the
+passphrase twice for every buffer save and every so often for file
+reads, since the gpg-agent caches your passphrase for file reads at
+least for some time, but not for buffer saves.
+
+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. 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.
+
+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 to be encrypted or decrypted. It
+creates them below the directory returned by function
+@code{temporary-file-directory}. If you want to be sure not to leave
+any plain-text traces, use an encrypted file systems at least for that
+directory.
+
The file name pattern for encrypted files can be controlled by
@code{epa-file-name-regexp}.
@@ -436,6 +481,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. Instead, consider using the gpg-agent, which in
+many cases can do the same job, and does it in a safer way.
+@xref{Caching Passphrases} for more information.
@end defvar
@defvar epa-file-inhibit-auto-save
@@ -461,8 +511,8 @@ Querying a key server
@node GnuPG version compatibility
@chapter GnuPG version compatibility
-As of February 2016, there are three active branches of GnuPG: 2.1,
-2.0, and 1.4. All those branches should work flawlessly with Emacs
+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.
@@ -490,17 +540,71 @@ GnuPG version compatibility
graphical prompt.
@end itemize
+
+@node GnuPG Pinentry
+@chapter GnuPG Pinentry
+
+An important component of the GnuPG suite is the Pinentry, which
+allows for secure entry of passphrases requests by GnuPG. GnuPG
+delivers various different programs as Pinentry, ranging from bland
+TTY-only @samp{pinentry-tty} to fancy graphical dialogues for various
+desktop environments, like @samp{pinentry-gnome3}. Your operating
+system usually determines which of these is used by default.
+
+With some configuration Emacs can also play the role of a Pinentry.
+There are three different scenarios possible@footnote{Not all
+operating systems and distributions support all of the above
+scenarios. As of June 2023 Debian GNU/Linux, for example, supports
+only the first of them due to security concerns.}:
+
+@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.
+@end enumerate
+
+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}.
+
@node Caching Passphrases
@chapter Caching Passphrases
Typing passphrases is a troublesome task if you frequently open and
close the same file. GnuPG and EasyPG Assistant provide mechanisms to
remember your passphrases for a limited time. Using these, you only
-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 (symmetric or public key),
-and whether or not you want to use gpg-agent. Here are some
+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
+(symmetric or public key), and whether or not you want to use
+gpg-agent (which is mandatory for GnuPG 2.0 and later). Here are some
questions:
@enumerate
^ permalink raw reply related [flat|nested] 24+ messages in thread
[parent not found: <83wn02r0s7.fsf@gnu.org>]
* bug#64154: Fwd: Some additions to the EasyPG Assistant's manual
[not found] <83wn02r0s7.fsf@gnu.org>
@ 2023-06-18 17:32 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-06-29 21:10 ` bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
0 siblings, 1 reply; 24+ messages in thread
From: Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2023-06-18 17:32 UTC (permalink / raw)
To: 64154
-------- 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@gnu.org>
To: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
CC: emacs-devel@gnu.org
> Date: Sun, 11 Jun 2023 20:00:12 +0200
> From: Jens Schmidt <jschmidt4gnu@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@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.
^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi
2023-06-18 17:32 ` bug#64154: Fwd: Some additions to the EasyPG Assistant's manual Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2023-06-29 21:10 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-06-30 5:54 ` Eli Zaretskii
2023-07-02 2:15 ` Richard Stallman
0 siblings, 2 replies; 24+ messages in thread
From: Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2023-06-29 21:10 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 64154
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
^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi
2023-06-29 21:10 ` bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2023-06-30 5:54 ` Eli Zaretskii
2023-06-30 19:13 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-02 2:15 ` Richard Stallman
1 sibling, 1 reply; 24+ messages in thread
From: Eli Zaretskii @ 2023-06-30 5:54 UTC (permalink / raw)
To: Jens Schmidt; +Cc: 64154
> Date: Thu, 29 Jun 2023 23:10:41 +0200
> From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
> Cc: 64154@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.
^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi
2023-06-30 5:54 ` Eli Zaretskii
@ 2023-06-30 19:13 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-06-30 19:32 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-01 5:37 ` Eli Zaretskii
0 siblings, 2 replies; 24+ messages in thread
From: Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2023-06-30 19:13 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 64154
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
^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi
2023-06-30 19:13 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2023-06-30 19:32 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-06-30 20:54 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-01 5:37 ` Eli Zaretskii
1 sibling, 1 reply; 24+ messages in thread
From: Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2023-06-30 19:32 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 64154
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.
^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi
2023-06-30 19:32 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2023-06-30 20:54 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-01 6:01 ` Eli Zaretskii
0 siblings, 1 reply; 24+ messages in thread
From: Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2023-06-30 20:54 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 64154
[-- Attachment #1: Type: text/plain, Size: 357 bytes --]
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
[-- Attachment #2: 0001-Add-concept-index-title-case-structure-titles.patch --]
[-- Type: text/x-patch, Size: 9013 bytes --]
From 4c3a7660acda89a542fc8916d5125dc3c83bf961 Mon Sep 17 00:00:00 2001
From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
Date: Fri, 30 Jun 2023 22:20:57 +0200
Subject: [PATCH] Add concept index, title-case structure titles
* doc/misc/epa.texi (Top, Overview, Quick start, Commands)
(Key management, Cryptographic operations on regions)
(Cryptographic operations on files, Dired integration)
(Mail-mode integration, Encrypting/decrypting gpg files)
(Querying a key server, GnuPG version compatibility, Caching Passphrases)
(GNU Free Documentation License): Add concept index, title-case
structure titles. (Bug#64154)
---
doc/misc/epa.texi | 85 +++++++++++++++++++++++++++++++++++++++++------
1 file changed, 74 insertions(+), 11 deletions(-)
diff --git a/doc/misc/epa.texi b/doc/misc/epa.texi
index 6f63a3d7ba0..c59f9b8630e 100644
--- a/doc/misc/epa.texi
+++ b/doc/misc/epa.texi
@@ -43,7 +43,11 @@
@contents
@node Top
-@top EasyPG Assistant user's manual
+@top EasyPG Assistant User's Manual
+@cindex easypg assistant
+@cindex easypg
+@cindex gnu privacy guard
+@cindex gnupg
EasyPG Assistant is an Emacs user interface to GNU Privacy Guard
(GnuPG, @pxref{Top, , Top, gnupg, Using the GNU Privacy Guard}).
@@ -56,6 +60,12 @@ Top
@insertcopying
@end ifnottex
+@c Unfortunately the node names of this manual are not very consistent
+@c w.r.t. their case. However, case is significant in node names, so
+@c we probably better should not change these to not break any
+@c external references. Things are more relaxed for structure titles,
+@c so we consistently updated them to title-case.
+
@menu
* Overview::
* Quick start::
@@ -64,6 +74,7 @@ Top
* Caching Passphrases::
* Bug Reports::
* GNU Free Documentation License:: The license for this documentation.
+* Concept Index::
* Key Index::
* Function Index::
* Variable Index::
@@ -71,6 +82,9 @@ Top
@node Overview
@chapter Overview
+@cindex overview
+@cindex feature overview
+@cindex features
EasyPG Assistant provides the following features.
@@ -84,7 +98,9 @@ Overview
@end itemize
@node Quick start
-@chapter Quick start
+@chapter Quick Start
+@cindex quick start
+@cindex introduction
EasyPG Assistant commands are prefixed by @samp{epa-}. For example,
@@ -104,6 +120,7 @@ Quick start
@node Commands
@chapter Commands
+@cindex commands
This chapter introduces various commands for typical use cases.
@@ -118,7 +135,11 @@ Commands
@end menu
@node Key management
-@section Key management
+@section Key Management
+@cindex key management
+@cindex key ring
+
+@cindex browse key ring
Probably the first step of using EasyPG Assistant is to browse your
keyring. @kbd{M-x epa-list-keys} is corresponding to @samp{gpg
--list-keys} from the command line.
@@ -157,6 +178,7 @@ Key management
Fingerprint: 9003 D76B 73B7 4A8A E588 10AF 4447 461B 2A9B EA2D
@end example
+@cindex browse private key ring
@noindent
To browse your private keyring, use @kbd{M-x epa-list-secret-keys}.
@@ -172,12 +194,14 @@ Key management
Below are other commands related to key management. Some of them take
a file as input/output, and others take the current region.
+@cindex insert key
@deffn Command epa-insert-keys keys
Insert selected @var{keys} after the point. It will let you select
keys before insertion. By default, it will encode keys in the OpenPGP
armor format.
@end deffn
+@cindex import key
@deffn Command epa-import-keys file
Import keys from @var{file} to your keyring.
@end deffn
@@ -195,14 +219,18 @@ Key management
applies @code{epa-import-keys-region} to each of them.
@end deffn
+@cindex delete key
@deffn Command epa-delete-keys allow-secret
Delete selected keys. If @var{allow-secret} is non-@code{nil}, it
also delete the secret keys.
@end deffn
@node Cryptographic operations on regions
-@section Cryptographic operations on regions
+@section Cryptographic Operations on Regions
+@cindex cryptographic operations on regions
+@cindex region operations
+@cindex decrypt region
@deffn Command epa-decrypt-region start end
Decrypt the current region between @var{start} and @var{end}. It
replaces the region with the decrypted text.
@@ -216,6 +244,7 @@ Cryptographic operations on regions
command does not alter the original text around armors.
@end deffn
+@cindex verify region
@deffn Command epa-verify-region start end
Verify the current region between @var{start} and @var{end}. It sends
the verification result to the minibuffer or a popup window. It
@@ -231,6 +260,7 @@ Cryptographic operations on regions
not alter the original text around OpenPGP cleartext blocks.
@end deffn
+@cindex sign region
@deffn Command epa-sign-region start end signers type
Sign the current region between @var{start} and @var{end}. By
default, it creates a cleartext signature. If a prefix argument is
@@ -238,6 +268,7 @@ Cryptographic operations on regions
type.
@end deffn
+@cindex encrypt region
@deffn Command epa-encrypt-region start end recipients sign signers
Encrypt the current region between @var{start} and @var{end}. It will
let you select recipients. If a prefix argument is given, it will
@@ -246,28 +277,37 @@ Cryptographic operations on regions
@end deffn
@node Cryptographic operations on files
-@section Cryptographic operations on files
+@section Cryptographic Operations on Files
+@cindex cryptographic operations on files
+@cindex file operations
+@cindex decrypt file
@deffn Command epa-decrypt-file file &optional output
Decrypt @var{file}. If you do not specify the name @var{output} to
use for the decrypted file, this function prompts for the value to use.
@end deffn
+@cindex verify file
@deffn Command epa-verify-file file
Verify @var{file}.
@end deffn
+@cindex sign file
@deffn Command epa-sign-file file signers type
Sign @var{file}. If a prefix argument is given, it will let you
select signing keys, and then a signature type.
@end deffn
+@cindex encrypt file
@deffn Command epa-encrypt-file file recipients
Encrypt @var{file}. It will let you select recipients.
@end deffn
@node Dired integration
-@section Dired integration
+@section Dired Integration
+@cindex dired integration
+@cindex directory operations
+@cindex multiple file operations
EasyPG Assistant extends Dired Mode for GNU Emacs to allow users to
easily do cryptographic operations on files. For example,
@@ -306,7 +346,10 @@ Dired integration
@end table
@node Mail-mode integration
-@section Mail-mode integration
+@section Mail-Mode Integration
+@cindex mail-mode integration
+@cindex sending signed mails
+@cindex sending encrypted mails
EasyPG Assistant provides a minor mode @code{epa-mail-mode} to help
user compose inline OpenPGP messages. Inline OpenPGP is a traditional
@@ -361,7 +404,12 @@ Mail-mode integration
@end table
@node Encrypting/decrypting gpg files
-@section Encrypting/decrypting gpg files
+@section Encrypting and Decrypting gpg Files
+@cindex encrypting gpg files
+@cindex decrypting gpg files
+@cindex gpg files
+@cindex automatic file encryption and decryption
+
By default, every file whose name ends with @file{.gpg} will be
treated as encrypted. That is, when you open such a file, the
decrypted text is inserted in the buffer rather than encrypted one.
@@ -444,7 +492,10 @@ Encrypting/decrypting gpg files
@end defvar
@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
The @code{epa-search-keys} command can be used to query a
@acronym{GPG} key server. Emacs will then pop up a buffer that lists
@@ -457,9 +508,11 @@ Querying a key server
The @code{epa-keyserver} variable says which server to query.
-
@node GnuPG version compatibility
-@chapter GnuPG version compatibility
+@chapter GnuPG Version Compatibility
+@cindex gnupg version compatibility
+@cindex version compatibility
+@cindex compatibility
As of February 2016, there are three active branches of GnuPG: 2.1,
2.0, and 1.4. All those branches should work flawlessly with Emacs
@@ -492,6 +545,10 @@ GnuPG version compatibility
@node Caching Passphrases
@chapter Caching Passphrases
+@cindex caching passphrases
+@cindex entering passphrases
+@cindex passphrase cache
+@cindex passphrases
Typing passphrases is a troublesome task if you frequently open and
close the same file. GnuPG and EasyPG Assistant provide mechanisms to
@@ -532,6 +589,8 @@ Caching Passphrases
@node Bug Reports
@chapter Bug Reports
+@cindex bug reports
+@cindex reporting bugs
Bugs and problems with EasyPG Assistant are actively worked on by the
Emacs development team. Feature requests and suggestions are also
@@ -556,6 +615,10 @@ GNU Free Documentation License
@appendix GNU Free Documentation License
@include doclicense.texi
+@node Concept Index
+@unnumbered Concept Index
+@printindex cp
+
@node Key Index
@unnumbered Key Index
@printindex ky
--
2.30.2
^ permalink raw reply related [flat|nested] 24+ messages in thread
* bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi
2023-06-30 20:54 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2023-07-01 6:01 ` Eli Zaretskii
2023-07-01 11:13 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-01 16:56 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
0 siblings, 2 replies; 24+ messages in thread
From: Eli Zaretskii @ 2023-07-01 6:01 UTC (permalink / raw)
To: Jens Schmidt; +Cc: 64154
> Date: Fri, 30 Jun 2023 22:54:11 +0200
> From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
> Cc: 64154@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.
^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi
2023-07-01 6:01 ` Eli Zaretskii
@ 2023-07-01 11:13 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-01 11:57 ` Eli Zaretskii
2023-07-01 16:56 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
1 sibling, 1 reply; 24+ messages in thread
From: Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2023-07-01 11:13 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 64154
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?
^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi
2023-07-01 11:13 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2023-07-01 11:57 ` Eli Zaretskii
0 siblings, 0 replies; 24+ messages in thread
From: Eli Zaretskii @ 2023-07-01 11:57 UTC (permalink / raw)
To: Jens Schmidt; +Cc: 64154
> Date: Sat, 1 Jul 2023 13:13:44 +0200
> Cc: 64154@debbugs.gnu.org
> From: Jens Schmidt <jschmidt4gnu@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.
^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi
2023-07-01 6:01 ` Eli Zaretskii
2023-07-01 11:13 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2023-07-01 16:56 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-01 17:19 ` Eli Zaretskii
1 sibling, 1 reply; 24+ messages in thread
From: Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2023-07-01 16:56 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 64154
[-- Attachment #1: Type: text/plain, Size: 2477 bytes --]
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 ...
[-- Attachment #2: 0002-Brush-up-index-entries-after-review.patch --]
[-- Type: text/x-patch, Size: 7522 bytes --]
From 9a60304d83edbb64e91e3cec60e9fba0d9ab043d Mon Sep 17 00:00:00 2001
From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
Date: Sat, 1 Jul 2023 18:51:17 +0200
Subject: [PATCH 2/2] Brush up index entries after review
* doc/misc/epa.texi (Top, Overview, Quick start, Commands)
(Key management, Cryptographic operations on regions, Dired integration)
(Encrypting/decrypting gpg files, Querying a key server)
(Caching Passphrases): Brush up index entries after review. (Bug#64154)
---
doc/misc/epa.texi | 64 +++++++++++++++++++++--------------------------
1 file changed, 28 insertions(+), 36 deletions(-)
diff --git a/doc/misc/epa.texi b/doc/misc/epa.texi
index c59f9b8630e..4b998939ef5 100644
--- a/doc/misc/epa.texi
+++ b/doc/misc/epa.texi
@@ -44,10 +44,9 @@
@node Top
@top EasyPG Assistant User's Manual
-@cindex easypg assistant
-@cindex easypg
-@cindex gnu privacy guard
-@cindex gnupg
+@cindex EasyPG Assistant
+@cindex GNU Privacy Guard
+@cindex GnuPG
EasyPG Assistant is an Emacs user interface to GNU Privacy Guard
(GnuPG, @pxref{Top, , Top, gnupg, Using the GNU Privacy Guard}).
@@ -82,9 +81,7 @@ Top
@node Overview
@chapter Overview
-@cindex overview
-@cindex feature overview
-@cindex features
+@cindex features of EasyPG Assistant
EasyPG Assistant provides the following features.
@@ -99,8 +96,7 @@ Overview
@node Quick start
@chapter Quick Start
-@cindex quick start
-@cindex introduction
+@cindex introduction to EasyPG Assistant
EasyPG Assistant commands are prefixed by @samp{epa-}. For example,
@@ -120,7 +116,6 @@ Quick start
@node Commands
@chapter Commands
-@cindex commands
This chapter introduces various commands for typical use cases.
@@ -137,9 +132,9 @@ Commands
@node Key management
@section Key Management
@cindex key management
-@cindex key ring
-@cindex browse key ring
+@cindex key ring, browsing
+@cindex browse the key ring
Probably the first step of using EasyPG Assistant is to browse your
keyring. @kbd{M-x epa-list-keys} is corresponding to @samp{gpg
--list-keys} from the command line.
@@ -178,7 +173,7 @@ Key management
Fingerprint: 9003 D76B 73B7 4A8A E588 10AF 4447 461B 2A9B EA2D
@end example
-@cindex browse private key ring
+@cindex private key ring, browsing
@noindent
To browse your private keyring, use @kbd{M-x epa-list-secret-keys}.
@@ -194,14 +189,14 @@ Key management
Below are other commands related to key management. Some of them take
a file as input/output, and others take the current region.
-@cindex insert key
+@cindex insert keys
@deffn Command epa-insert-keys keys
Insert selected @var{keys} after the point. It will let you select
keys before insertion. By default, it will encode keys in the OpenPGP
armor format.
@end deffn
-@cindex import key
+@cindex import keys
@deffn Command epa-import-keys file
Import keys from @var{file} to your keyring.
@end deffn
@@ -219,7 +214,7 @@ Key management
applies @code{epa-import-keys-region} to each of them.
@end deffn
-@cindex delete key
+@cindex delete keys
@deffn Command epa-delete-keys allow-secret
Delete selected keys. If @var{allow-secret} is non-@code{nil}, it
also delete the secret keys.
@@ -230,7 +225,7 @@ Cryptographic operations on regions
@cindex cryptographic operations on regions
@cindex region operations
-@cindex decrypt region
+@cindex decrypt a region
@deffn Command epa-decrypt-region start end
Decrypt the current region between @var{start} and @var{end}. It
replaces the region with the decrypted text.
@@ -244,7 +239,7 @@ Cryptographic operations on regions
command does not alter the original text around armors.
@end deffn
-@cindex verify region
+@cindex verify a region
@deffn Command epa-verify-region start end
Verify the current region between @var{start} and @var{end}. It sends
the verification result to the minibuffer or a popup window. It
@@ -260,7 +255,7 @@ Cryptographic operations on regions
not alter the original text around OpenPGP cleartext blocks.
@end deffn
-@cindex sign region
+@cindex sign a region
@deffn Command epa-sign-region start end signers type
Sign the current region between @var{start} and @var{end}. By
default, it creates a cleartext signature. If a prefix argument is
@@ -268,7 +263,7 @@ Cryptographic operations on regions
type.
@end deffn
-@cindex encrypt region
+@cindex encrypt a region
@deffn Command epa-encrypt-region start end recipients sign signers
Encrypt the current region between @var{start} and @var{end}. It will
let you select recipients. If a prefix argument is given, it will
@@ -279,26 +274,26 @@ Cryptographic operations on regions
@node Cryptographic operations on files
@section Cryptographic Operations on Files
@cindex cryptographic operations on files
-@cindex file operations
+@cindex file operations, cryptographic
-@cindex decrypt file
+@cindex decrypt a file
@deffn Command epa-decrypt-file file &optional output
Decrypt @var{file}. If you do not specify the name @var{output} to
use for the decrypted file, this function prompts for the value to use.
@end deffn
-@cindex verify file
+@cindex verify a file
@deffn Command epa-verify-file file
Verify @var{file}.
@end deffn
-@cindex sign file
+@cindex sign a file
@deffn Command epa-sign-file file signers type
Sign @var{file}. If a prefix argument is given, it will let you
select signing keys, and then a signature type.
@end deffn
-@cindex encrypt file
+@cindex encrypt a file
@deffn Command epa-encrypt-file file recipients
Encrypt @var{file}. It will let you select recipients.
@end deffn
@@ -348,8 +343,7 @@ Dired integration
@node Mail-mode integration
@section Mail-Mode Integration
@cindex mail-mode integration
-@cindex sending signed mails
-@cindex sending encrypted mails
+@cindex sending signed/encrypted mails
EasyPG Assistant provides a minor mode @code{epa-mail-mode} to help
user compose inline OpenPGP messages. Inline OpenPGP is a traditional
@@ -407,7 +401,7 @@ Encrypting/decrypting gpg files
@section Encrypting and Decrypting gpg Files
@cindex encrypting gpg files
@cindex decrypting gpg files
-@cindex gpg files
+@cindex gpg files, encrypting and decrypting
@cindex automatic file encryption and decryption
By default, every file whose name ends with @file{.gpg} will be
@@ -493,9 +487,8 @@ Encrypting/decrypting gpg files
@node Querying a key server
@section Querying a Key Server
-@cindex querying key server
-@cindex query key server
-@cindex key server
+@cindex query a key server
+@cindex key server, querying
The @code{epa-search-keys} command can be used to query a
@acronym{GPG} key server. Emacs will then pop up a buffer that lists
@@ -510,9 +503,9 @@ Querying a key server
@node GnuPG version compatibility
@chapter GnuPG Version Compatibility
-@cindex gnupg version compatibility
-@cindex version compatibility
-@cindex compatibility
+@cindex GnuPG version compatibility
+@cindex version compatibility with GnuPG
+@cindex compatibility with GnuPG
As of February 2016, there are three active branches of GnuPG: 2.1,
2.0, and 1.4. All those branches should work flawlessly with Emacs
@@ -547,8 +540,7 @@ Caching Passphrases
@chapter Caching Passphrases
@cindex caching passphrases
@cindex entering passphrases
-@cindex passphrase cache
-@cindex passphrases
+@cindex passphrases, entering and caching
Typing passphrases is a troublesome task if you frequently open and
close the same file. GnuPG and EasyPG Assistant provide mechanisms to
--
2.30.2
^ permalink raw reply related [flat|nested] 24+ messages in thread
* bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi
2023-07-01 16:56 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2023-07-01 17:19 ` Eli Zaretskii
2023-07-01 17:56 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
0 siblings, 1 reply; 24+ messages in thread
From: Eli Zaretskii @ 2023-07-01 17:19 UTC (permalink / raw)
To: Jens Schmidt; +Cc: 64154
> Date: Sat, 1 Jul 2023 18:56:20 +0200
> Cc: 64154@debbugs.gnu.org
> From: Jens Schmidt <jschmidt4gnu@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.
^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi
2023-07-01 17:19 ` Eli Zaretskii
@ 2023-07-01 17:56 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-01 18:49 ` Eli Zaretskii
0 siblings, 1 reply; 24+ messages in thread
From: Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2023-07-01 17:56 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 64154
On 2023-07-01 19:19, Eli Zaretskii wrote:
>> Date: Sat, 1 Jul 2023 18:56:20 +0200 Cc: 64154@debbugs.gnu.org
>> From: Jens Schmidt <jschmidt4gnu@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 ...
^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi
2023-07-01 17:56 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2023-07-01 18:49 ` Eli Zaretskii
2023-07-01 20:20 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
0 siblings, 1 reply; 24+ messages in thread
From: Eli Zaretskii @ 2023-07-01 18:49 UTC (permalink / raw)
To: Jens Schmidt; +Cc: 64154
> Date: Sat, 1 Jul 2023 19:56:08 +0200
> Cc: 64154@debbugs.gnu.org
> From: Jens Schmidt <jschmidt4gnu@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.
^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi
2023-07-01 18:49 ` Eli Zaretskii
@ 2023-07-01 20:20 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-02 4:59 ` Eli Zaretskii
0 siblings, 1 reply; 24+ messages in thread
From: Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2023-07-01 20:20 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 64154
[-- Attachment #1: Type: text/plain, Size: 1093 bytes --]
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.
[-- Attachment #2: 0003-Brush-up-index-entries-after-review.patch --]
[-- Type: text/x-patch, Size: 4925 bytes --]
From 8335d96553e2d29df0bffceaef9022c38beab1ff Mon Sep 17 00:00:00 2001
From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
Date: Sat, 1 Jul 2023 21:53:31 +0200
Subject: [PATCH] Brush up index entries after review
* doc/misc/epa.texi (Top, Overview, Key management)
(Cryptographic operations on regions, Cryptographic operations on files)
(Encrypting/decrypting gpg files, Querying a key server): Brush up
index entries after review. (Bug#64154)
---
doc/misc/epa.texi | 38 +++++++++++++++++++-------------------
1 file changed, 19 insertions(+), 19 deletions(-)
diff --git a/doc/misc/epa.texi b/doc/misc/epa.texi
index 4b998939ef5..edfe37de816 100644
--- a/doc/misc/epa.texi
+++ b/doc/misc/epa.texi
@@ -44,9 +44,9 @@
@node Top
@top EasyPG Assistant User's Manual
-@cindex EasyPG Assistant
-@cindex GNU Privacy Guard
-@cindex GnuPG
+@cindex easypg assistant
+@cindex gnu privacy guard
+@cindex gnupg
EasyPG Assistant is an Emacs user interface to GNU Privacy Guard
(GnuPG, @pxref{Top, , Top, gnupg, Using the GNU Privacy Guard}).
@@ -81,7 +81,7 @@ Top
@node Overview
@chapter Overview
-@cindex features of EasyPG Assistant
+@cindex features of easypg assistant
EasyPG Assistant provides the following features.
@@ -96,7 +96,7 @@ Overview
@node Quick start
@chapter Quick Start
-@cindex introduction to EasyPG Assistant
+@cindex introduction to easypg assistant
EasyPG Assistant commands are prefixed by @samp{epa-}. For example,
@@ -134,7 +134,7 @@ Key management
@cindex key management
@cindex key ring, browsing
-@cindex browse the key ring
+@cindex browse key ring
Probably the first step of using EasyPG Assistant is to browse your
keyring. @kbd{M-x epa-list-keys} is corresponding to @samp{gpg
--list-keys} from the command line.
@@ -223,9 +223,9 @@ Key management
@node Cryptographic operations on regions
@section Cryptographic Operations on Regions
@cindex cryptographic operations on regions
-@cindex region operations
+@cindex region operations, cryptographic
-@cindex decrypt a region
+@cindex decrypt region
@deffn Command epa-decrypt-region start end
Decrypt the current region between @var{start} and @var{end}. It
replaces the region with the decrypted text.
@@ -239,7 +239,7 @@ Cryptographic operations on regions
command does not alter the original text around armors.
@end deffn
-@cindex verify a region
+@cindex verify region
@deffn Command epa-verify-region start end
Verify the current region between @var{start} and @var{end}. It sends
the verification result to the minibuffer or a popup window. It
@@ -255,7 +255,7 @@ Cryptographic operations on regions
not alter the original text around OpenPGP cleartext blocks.
@end deffn
-@cindex sign a region
+@cindex sign region
@deffn Command epa-sign-region start end signers type
Sign the current region between @var{start} and @var{end}. By
default, it creates a cleartext signature. If a prefix argument is
@@ -263,7 +263,7 @@ Cryptographic operations on regions
type.
@end deffn
-@cindex encrypt a region
+@cindex encrypt region
@deffn Command epa-encrypt-region start end recipients sign signers
Encrypt the current region between @var{start} and @var{end}. It will
let you select recipients. If a prefix argument is given, it will
@@ -276,24 +276,24 @@ Cryptographic operations on files
@cindex cryptographic operations on files
@cindex file operations, cryptographic
-@cindex decrypt a file
+@cindex decrypt file
@deffn Command epa-decrypt-file file &optional output
Decrypt @var{file}. If you do not specify the name @var{output} to
use for the decrypted file, this function prompts for the value to use.
@end deffn
-@cindex verify a file
+@cindex verify file
@deffn Command epa-verify-file file
Verify @var{file}.
@end deffn
-@cindex sign a file
+@cindex sign file
@deffn Command epa-sign-file file signers type
Sign @var{file}. If a prefix argument is given, it will let you
select signing keys, and then a signature type.
@end deffn
-@cindex encrypt a file
+@cindex encrypt file
@deffn Command epa-encrypt-file file recipients
Encrypt @var{file}. It will let you select recipients.
@end deffn
@@ -487,7 +487,7 @@ Encrypting/decrypting gpg files
@node Querying a key server
@section Querying a Key Server
-@cindex query a key server
+@cindex query key server
@cindex key server, querying
The @code{epa-search-keys} command can be used to query a
@@ -503,9 +503,9 @@ Querying a key server
@node GnuPG version compatibility
@chapter GnuPG Version Compatibility
-@cindex GnuPG version compatibility
-@cindex version compatibility with GnuPG
-@cindex compatibility with GnuPG
+@cindex gnupg version compatibility
+@cindex version compatibility with gnupg
+@cindex compatibility with gnupg
As of February 2016, there are three active branches of GnuPG: 2.1,
2.0, and 1.4. All those branches should work flawlessly with Emacs
--
2.30.2
^ permalink raw reply related [flat|nested] 24+ messages in thread
* bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi
2023-07-01 20:20 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2023-07-02 4:59 ` Eli Zaretskii
2023-07-02 7:13 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
0 siblings, 1 reply; 24+ messages in thread
From: Eli Zaretskii @ 2023-07-02 4:59 UTC (permalink / raw)
To: Jens Schmidt; +Cc: 64154
> Date: Sat, 1 Jul 2023 22:20:12 +0200
> Cc: 64154@debbugs.gnu.org
> From: Jens Schmidt <jschmidt4gnu@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?
^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi
2023-07-02 4:59 ` Eli Zaretskii
@ 2023-07-02 7:13 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-02 8:18 ` Eli Zaretskii
0 siblings, 1 reply; 24+ messages in thread
From: Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2023-07-02 7:13 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 64154
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.
^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi
2023-07-02 7:13 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2023-07-02 8:18 ` Eli Zaretskii
2023-07-02 11:54 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-02 11:55 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
0 siblings, 2 replies; 24+ messages in thread
From: Eli Zaretskii @ 2023-07-02 8:18 UTC (permalink / raw)
To: Jens Schmidt; +Cc: 64154
> Date: Sun, 2 Jul 2023 09:13:25 +0200
> Cc: 64154@debbugs.gnu.org
> From: Jens Schmidt <jschmidt4gnu@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?
^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi
2023-07-02 8:18 ` Eli Zaretskii
@ 2023-07-02 11:54 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-02 12:16 ` Eli Zaretskii
2023-07-02 11:55 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
1 sibling, 1 reply; 24+ messages in thread
From: Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2023-07-02 11:54 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 64154
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)?
^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi
2023-07-02 11:54 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2023-07-02 12:16 ` Eli Zaretskii
0 siblings, 0 replies; 24+ messages in thread
From: Eli Zaretskii @ 2023-07-02 12:16 UTC (permalink / raw)
To: Jens Schmidt; +Cc: 64154
> Date: Sun, 2 Jul 2023 13:54:16 +0200
> Cc: 64154@debbugs.gnu.org
> From: Jens Schmidt <jschmidt4gnu@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.
^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi
2023-07-02 8:18 ` Eli Zaretskii
2023-07-02 11:54 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2023-07-02 11:55 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-02 12:18 ` Eli Zaretskii
1 sibling, 1 reply; 24+ messages in thread
From: Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2023-07-02 11:55 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 64154
[-- Attachment #1: Type: text/plain, Size: 126 bytes --]
On 2023-07-02 10:18, Eli Zaretskii wrote:
> Can you send a single patch with all the changes, please?
Here you go.
Thanks
[-- Attachment #2: 0001-Add-concept-index-title-case-structure-titles.patch --]
[-- Type: text/x-patch, Size: 8848 bytes --]
From aca7182f57d3ef23c1a422c9a171de672b1a036c Mon Sep 17 00:00:00 2001
From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
Date: Sun, 2 Jul 2023 13:39:48 +0200
Subject: [PATCH] Add concept index, title-case structure titles
* doc/misc/epa.texi (Top, Overview, Commands, Key management)
(Cryptographic operations on regions, Cryptographic operations on files)
(Dired integration, Mail-mode integration)
(Encrypting/decrypting gpg files, Querying a key server)
(GnuPG version compatibility, Caching Passphrases)
(GNU Free Documentation License): Add concept index, title-case
structure titles. (Bug#64154)
---
doc/misc/epa.texi | 77 ++++++++++++++++++++++++++++++++++++++++-------
1 file changed, 66 insertions(+), 11 deletions(-)
diff --git a/doc/misc/epa.texi b/doc/misc/epa.texi
index 6f63a3d7ba0..edfe37de816 100644
--- a/doc/misc/epa.texi
+++ b/doc/misc/epa.texi
@@ -43,7 +43,10 @@
@contents
@node Top
-@top EasyPG Assistant user's manual
+@top EasyPG Assistant User's Manual
+@cindex easypg assistant
+@cindex gnu privacy guard
+@cindex gnupg
EasyPG Assistant is an Emacs user interface to GNU Privacy Guard
(GnuPG, @pxref{Top, , Top, gnupg, Using the GNU Privacy Guard}).
@@ -56,6 +59,12 @@ Top
@insertcopying
@end ifnottex
+@c Unfortunately the node names of this manual are not very consistent
+@c w.r.t. their case. However, case is significant in node names, so
+@c we probably better should not change these to not break any
+@c external references. Things are more relaxed for structure titles,
+@c so we consistently updated them to title-case.
+
@menu
* Overview::
* Quick start::
@@ -64,6 +73,7 @@ Top
* Caching Passphrases::
* Bug Reports::
* GNU Free Documentation License:: The license for this documentation.
+* Concept Index::
* Key Index::
* Function Index::
* Variable Index::
@@ -71,6 +81,7 @@ Top
@node Overview
@chapter Overview
+@cindex features of easypg assistant
EasyPG Assistant provides the following features.
@@ -84,7 +95,8 @@ Overview
@end itemize
@node Quick start
-@chapter Quick start
+@chapter Quick Start
+@cindex introduction to easypg assistant
EasyPG Assistant commands are prefixed by @samp{epa-}. For example,
@@ -118,7 +130,11 @@ Commands
@end menu
@node Key management
-@section Key management
+@section Key Management
+@cindex key management
+
+@cindex key ring, browsing
+@cindex browse key ring
Probably the first step of using EasyPG Assistant is to browse your
keyring. @kbd{M-x epa-list-keys} is corresponding to @samp{gpg
--list-keys} from the command line.
@@ -157,6 +173,7 @@ Key management
Fingerprint: 9003 D76B 73B7 4A8A E588 10AF 4447 461B 2A9B EA2D
@end example
+@cindex private key ring, browsing
@noindent
To browse your private keyring, use @kbd{M-x epa-list-secret-keys}.
@@ -172,12 +189,14 @@ Key management
Below are other commands related to key management. Some of them take
a file as input/output, and others take the current region.
+@cindex insert keys
@deffn Command epa-insert-keys keys
Insert selected @var{keys} after the point. It will let you select
keys before insertion. By default, it will encode keys in the OpenPGP
armor format.
@end deffn
+@cindex import keys
@deffn Command epa-import-keys file
Import keys from @var{file} to your keyring.
@end deffn
@@ -195,14 +214,18 @@ Key management
applies @code{epa-import-keys-region} to each of them.
@end deffn
+@cindex delete keys
@deffn Command epa-delete-keys allow-secret
Delete selected keys. If @var{allow-secret} is non-@code{nil}, it
also delete the secret keys.
@end deffn
@node Cryptographic operations on regions
-@section Cryptographic operations on regions
+@section Cryptographic Operations on Regions
+@cindex cryptographic operations on regions
+@cindex region operations, cryptographic
+@cindex decrypt region
@deffn Command epa-decrypt-region start end
Decrypt the current region between @var{start} and @var{end}. It
replaces the region with the decrypted text.
@@ -216,6 +239,7 @@ Cryptographic operations on regions
command does not alter the original text around armors.
@end deffn
+@cindex verify region
@deffn Command epa-verify-region start end
Verify the current region between @var{start} and @var{end}. It sends
the verification result to the minibuffer or a popup window. It
@@ -231,6 +255,7 @@ Cryptographic operations on regions
not alter the original text around OpenPGP cleartext blocks.
@end deffn
+@cindex sign region
@deffn Command epa-sign-region start end signers type
Sign the current region between @var{start} and @var{end}. By
default, it creates a cleartext signature. If a prefix argument is
@@ -238,6 +263,7 @@ Cryptographic operations on regions
type.
@end deffn
+@cindex encrypt region
@deffn Command epa-encrypt-region start end recipients sign signers
Encrypt the current region between @var{start} and @var{end}. It will
let you select recipients. If a prefix argument is given, it will
@@ -246,28 +272,37 @@ Cryptographic operations on regions
@end deffn
@node Cryptographic operations on files
-@section Cryptographic operations on files
+@section Cryptographic Operations on Files
+@cindex cryptographic operations on files
+@cindex file operations, cryptographic
+@cindex decrypt file
@deffn Command epa-decrypt-file file &optional output
Decrypt @var{file}. If you do not specify the name @var{output} to
use for the decrypted file, this function prompts for the value to use.
@end deffn
+@cindex verify file
@deffn Command epa-verify-file file
Verify @var{file}.
@end deffn
+@cindex sign file
@deffn Command epa-sign-file file signers type
Sign @var{file}. If a prefix argument is given, it will let you
select signing keys, and then a signature type.
@end deffn
+@cindex encrypt file
@deffn Command epa-encrypt-file file recipients
Encrypt @var{file}. It will let you select recipients.
@end deffn
@node Dired integration
-@section Dired integration
+@section Dired Integration
+@cindex dired integration
+@cindex directory operations
+@cindex multiple file operations
EasyPG Assistant extends Dired Mode for GNU Emacs to allow users to
easily do cryptographic operations on files. For example,
@@ -306,7 +341,9 @@ Dired integration
@end table
@node Mail-mode integration
-@section Mail-mode integration
+@section Mail-Mode Integration
+@cindex mail-mode integration
+@cindex sending signed/encrypted mails
EasyPG Assistant provides a minor mode @code{epa-mail-mode} to help
user compose inline OpenPGP messages. Inline OpenPGP is a traditional
@@ -361,7 +398,12 @@ Mail-mode integration
@end table
@node Encrypting/decrypting gpg files
-@section Encrypting/decrypting gpg files
+@section Encrypting and Decrypting gpg Files
+@cindex encrypting gpg files
+@cindex decrypting gpg files
+@cindex gpg files, encrypting and decrypting
+@cindex automatic file encryption and decryption
+
By default, every file whose name ends with @file{.gpg} will be
treated as encrypted. That is, when you open such a file, the
decrypted text is inserted in the buffer rather than encrypted one.
@@ -444,7 +486,9 @@ Encrypting/decrypting gpg files
@end defvar
@node Querying a key server
-@section Querying a key server
+@section Querying a Key Server
+@cindex query key server
+@cindex key server, querying
The @code{epa-search-keys} command can be used to query a
@acronym{GPG} key server. Emacs will then pop up a buffer that lists
@@ -457,9 +501,11 @@ Querying a key server
The @code{epa-keyserver} variable says which server to query.
-
@node GnuPG version compatibility
-@chapter GnuPG version compatibility
+@chapter GnuPG Version Compatibility
+@cindex gnupg version compatibility
+@cindex version compatibility with gnupg
+@cindex compatibility with gnupg
As of February 2016, there are three active branches of GnuPG: 2.1,
2.0, and 1.4. All those branches should work flawlessly with Emacs
@@ -492,6 +538,9 @@ GnuPG version compatibility
@node Caching Passphrases
@chapter Caching Passphrases
+@cindex caching passphrases
+@cindex entering passphrases
+@cindex passphrases, entering and caching
Typing passphrases is a troublesome task if you frequently open and
close the same file. GnuPG and EasyPG Assistant provide mechanisms to
@@ -532,6 +581,8 @@ Caching Passphrases
@node Bug Reports
@chapter Bug Reports
+@cindex bug reports
+@cindex reporting bugs
Bugs and problems with EasyPG Assistant are actively worked on by the
Emacs development team. Feature requests and suggestions are also
@@ -556,6 +607,10 @@ GNU Free Documentation License
@appendix GNU Free Documentation License
@include doclicense.texi
+@node Concept Index
+@unnumbered Concept Index
+@printindex cp
+
@node Key Index
@unnumbered Key Index
@printindex ky
--
2.30.2
^ permalink raw reply related [flat|nested] 24+ messages in thread
* bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi
2023-06-30 19:13 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-06-30 19:32 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2023-07-01 5:37 ` Eli Zaretskii
1 sibling, 0 replies; 24+ messages in thread
From: Eli Zaretskii @ 2023-07-01 5:37 UTC (permalink / raw)
To: Jens Schmidt; +Cc: 64154
> Date: Fri, 30 Jun 2023 21:13:40 +0200
> Cc: 64154@debbugs.gnu.org
> From: Jens Schmidt <jschmidt4gnu@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.
^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi
2023-06-29 21:10 ` bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-06-30 5:54 ` Eli Zaretskii
@ 2023-07-02 2:15 ` Richard Stallman
2023-07-02 7:34 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
1 sibling, 1 reply; 24+ messages in thread
From: Richard Stallman @ 2023-07-02 2:15 UTC (permalink / raw)
To: Jens Schmidt; +Cc: eliz, 64154
[[[ 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)
^ permalink raw reply [flat|nested] 24+ messages in thread
* bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi
2023-07-02 2:15 ` Richard Stallman
@ 2023-07-02 7:34 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
0 siblings, 0 replies; 24+ messages in thread
From: Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2023-07-02 7:34 UTC (permalink / raw)
To: rms; +Cc: eliz, 64154
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.
^ permalink raw reply [flat|nested] 24+ messages in thread
end of thread, other threads:[~2023-07-02 12:18 UTC | newest]
Thread overview: 24+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-06-18 17:29 bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
[not found] <83wn02r0s7.fsf@gnu.org>
2023-06-18 17:32 ` bug#64154: Fwd: Some additions to the EasyPG Assistant's manual Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-06-29 21:10 ` bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-06-30 5:54 ` Eli Zaretskii
2023-06-30 19:13 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-06-30 19:32 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-06-30 20:54 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-01 6:01 ` Eli Zaretskii
2023-07-01 11:13 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-01 11:57 ` Eli Zaretskii
2023-07-01 16:56 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-01 17:19 ` Eli Zaretskii
2023-07-01 17:56 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-01 18:49 ` Eli Zaretskii
2023-07-01 20:20 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-02 4:59 ` Eli Zaretskii
2023-07-02 7:13 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-02 8:18 ` Eli Zaretskii
2023-07-02 11:54 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-02 12:16 ` Eli Zaretskii
2023-07-02 11:55 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-02 12:18 ` Eli Zaretskii
2023-07-01 5:37 ` Eli Zaretskii
2023-07-02 2:15 ` Richard Stallman
2023-07-02 7:34 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).