Mention pinentry.el in epa manual

* doc/misc/epa.texi (GnuPG version compatibility): New chapter,
describing the differences between three GnuPG branches, and how
to enable pinentry.el.
(Caching Passphrases): Add xref to the compatibility chapter.

1 files changed, 51 insertions, 21 deletions

diff --git a/doc/misc/epa.texi b/doc/misc/epa.texi
index 527b44fb180..4b7b11834b3 100644
--- a/doc/misc/epa.texi
+++ b/doc/misc/epa.texi
@@ -42,7 +42,7 @@ modify this GNU manual.''
 
 @contents
 
-@node Top
+@node Top, Overview, (dir), (dir)
 @top EasyPG Assistant user's manual
 
 EasyPG Assistant is an Emacs user interface to GNU Privacy Guard
@@ -61,6 +61,7 @@ called EasyPG Library.
 * Quick start::
 * Commands::
 * Caching Passphrases::
+* GnuPG version compatibility::
 * Bug Reports::
 * GNU Free Documentation License::  The license for this documentation.
 * Key Index::
@@ -68,7 +69,7 @@ called EasyPG Library.
 * Variable Index::
 @end menu
 
-@node  Overview
+@node  Overview, Quick start, Top, Top
 @chapter Overview
 
 EasyPG Assistant provides the following features.
@@ -82,7 +83,7 @@ EasyPG Assistant provides the following features.
 @item Automatic encryption/decryption of *.gpg files.
 @end itemize
 
-@node  Quick start
+@node  Quick start, Commands, Overview, Top
 @chapter Quick start
 
 EasyPG Assistant commands are prefixed by @samp{epa-}.  For example,
@@ -99,7 +100,7 @@ EasyPG Assistant provides several cryptographic features which can be
 integrated into other Emacs functionalities.  For example, automatic
 encryption/decryption of @file{*.gpg} files.
 
-@node Commands
+@node Commands, GnuPG version compatibility, Quick start, Top
 @chapter Commands
 
 This chapter introduces various commands for typical use cases.
@@ -113,7 +114,7 @@ This chapter introduces various commands for typical use cases.
 * Encrypting/decrypting gpg files::
 @end menu
 
-@node Key management
+@node Key management, Cryptographic operations on regions, Commands, Commands
 @section Key management
 Probably the first step of using EasyPG Assistant is to browse your
 keyring.  @kbd{M-x epa-list-keys} is corresponding to @samp{gpg
@@ -196,7 +197,7 @@ Delete selected keys.  If @var{allow-secret} is non-@code{nil}, it
 also delete the secret keys.
 @end deffn
 
-@node Cryptographic operations on regions
+@node Cryptographic operations on regions, Cryptographic operations on files, Key management, Commands
 @section Cryptographic operations on regions
 
 @deffn Command epa-decrypt-region start end
@@ -241,7 +242,7 @@ also ask you whether or not to sign the text before encryption and if
 you answered yes, it will let you select the signing keys.
 @end deffn
 
-@node Cryptographic operations on files
+@node Cryptographic operations on files, Dired integration, Cryptographic operations on regions, Commands
 @section Cryptographic operations on files
 
 @deffn Command epa-decrypt-file file &optional output
@@ -262,7 +263,7 @@ select signing keys, and then a signature type.
 Encrypt @var{file}.  It will let you select recipients.
 @end deffn
 
-@node Dired integration
+@node Dired integration, Mail-mode integration, Cryptographic operations on files, Commands
 @section Dired integration
 
 EasyPG Assistant extends Dired Mode for GNU Emacs to allow users to
@@ -301,7 +302,7 @@ Encrypt marked files.
 
 @end table
 
-@node Mail-mode integration
+@node Mail-mode integration, Encrypting/decrypting gpg files, Dired integration, Commands
 @section Mail-mode integration
 
 EasyPG Assistant provides a minor mode @code{epa-mail-mode} to help
@@ -353,7 +354,7 @@ use that option to ignore specific recipients for encryption purposes.
 
 @end table
 
-@node Encrypting/decrypting gpg files
+@node Encrypting/decrypting gpg files,  , Mail-mode integration, Commands
 @section Encrypting/decrypting gpg files
 By default, every file whose name ends with @file{.gpg} will be
 treated as encrypted.  That is, when you open such a file, the
@@ -436,18 +437,47 @@ If non-@code{nil}, disable auto-saving when opening an encrypted file.
 The default value is @code{t}.
 @end defvar
 
-@node Caching Passphrases
+@node GnuPG version compatibility, Caching Passphrases, Commands, Top
+@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,
+with basic use-cases.  They have, however, some incompatible
+characteristics, which might be visible when used from Emacs.
+
+@itemize
+@item
+The key store format used by 2.1 is incompatible with 1.4.  That
+means, a key created with 2.1 might not be visible with 1.4.
+
+@item
+2.1 uses a fixed Unix domain socket for gpg-agent, and ignores the
+@code{GPG_AGENT_INFO} environment variable, used by 2.0 and 1.4.
+
+@item
+2.1 (2.1.5 or later) has a mechanism to direct the Pinentry password
+prompt to the Emacs minibuffer@footnote{To enable this feature, add
+@samp{allow-emacs-pinentry} to @file{~/.gnupg/gpg-agent.conf} and let
+gpg-agent reload the configuration, with: @samp{gpgconf --reload gpg-agent}},
+which would be useful when you use Emacs remotely or from a text-only
+terminal.  That feature is not available in other versions, and more
+specifically, with 2.0 (as of 2.0.29), there is no way to avoid the
+graphical prompt.
+@end itemize
+
+@node Caching Passphrases, Bug Reports, GnuPG version compatibility, Top
 @chapter Caching Passphrases
 
-Typing passphrases is an irritating task if you frequently open and
+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.  However, the configuration is a bit
-confusing since it depends on your GnuPG installation (GnuPG version 1 or
-GnuPG version 2), encryption method (symmetric or public key), and whether or
-not you want to use gpg-agent.  Here are some questions:
+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
+questions:
 
 @enumerate
-@item Do you use GnuPG version 2 instead of GnuPG version 1?
+@item Do you use GnuPG version 2.1 or 2.0 instead of GnuPG version 1.4?
 @item Do you use symmetric encryption rather than public key encryption?
 @item Do you want to use gpg-agent?
 @end enumerate
@@ -473,7 +503,7 @@ To set up elisp passphrase cache, set
 @code{epa-file-cache-passphrase-for-symmetric-encryption}.
 @xref{Encrypting/decrypting gpg files}.
 
-@node Bug Reports
+@node Bug Reports, GNU Free Documentation License, Caching Passphrases, Top
 @chapter Bug Reports
 
 Bugs and problems with EasyPG Assistant are actively worked on by the
@@ -495,19 +525,19 @@ Before reporting the bug, you should set @code{epg-debug} in the
 of the @file{ *epg-debug*} buffer.  Note that the first letter of the
 buffer name is a whitespace.
 
-@node GNU Free Documentation License
+@node GNU Free Documentation License, Key Index, Bug Reports, Top
 @appendix GNU Free Documentation License
 @include doclicense.texi
 
-@node Key Index
+@node Key Index, Function Index, GNU Free Documentation License, Top
 @unnumbered Key Index
 @printindex ky
 
-@node Function Index
+@node Function Index, Variable Index, Key Index, Top
 @unnumbered Function Index
 @printindex fn
 
-@node Variable Index
+@node Variable Index,  , Function Index, Top
 @unnumbered Variable Index
 @printindex vr