From: Eli Zaretskii <eliz@gnu.org>
To: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
Cc: 64154@debbugs.gnu.org
Subject: bug#64154: 29.0.92; Provide additional details on GnuPG and EPA usage in epa.texi
Date: Sat, 01 Jul 2023 09:01:36 +0300 [thread overview]
Message-ID: <83a5wgrwzj.fsf@gnu.org> (raw)
In-Reply-To: <3036a576-9260-8932-cb07-3941046f2dd8@vodafonemail.de> (message from Jens Schmidt on Fri, 30 Jun 2023 22:54:11 +0200)
> 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.
next prev parent reply other threads:[~2023-07-01 6:01 UTC|newest]
Thread overview: 34+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <dcb43cbb-61aa-417a-7da0-1b86223038ef@vodafonemail.de>
[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 [this message]
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
2023-07-08 20:31 ` bug#64154: Some additions to the EasyPG Assistant's manual Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-09 7:24 ` Eli Zaretskii
2023-07-09 10:18 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-09 11:26 ` Eli Zaretskii
2023-07-09 14:41 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-11 11:02 ` Eli Zaretskii
2023-07-11 20:24 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-07-13 7:52 ` Eli Zaretskii
2023-07-13 18:46 ` Jens Schmidt via Bug reports for GNU Emacs, the Swiss army knife of text editors
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
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=83a5wgrwzj.fsf@gnu.org \
--to=eliz@gnu.org \
--cc=64154@debbugs.gnu.org \
--cc=jschmidt4gnu@vodafonemail.de \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).