[Emacs-diffs] emacs-25 27d3430: Mention pinentry.el in epa manual

[Daiki Ueno]

branch: emacs-25
commit 27d343070d02210316e69e4f7da1faeea2d87608
Author: Daiki Ueno <address@hidden>
Commit: Daiki Ueno <address@hidden>

    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.
---
 doc/misc/epa.texi |   72 +++++++++++++++++++++++++++++++++++++---------------
 1 files changed, 51 insertions(+), 21 deletions(-)

diff --git a/doc/misc/epa.texi b/doc/misc/epa.texi
index 527b44f..4b7b118 100644
--- a/doc/misc/epa.texi
+++ b/doc/misc/epa.texi
@@ -42,7 +42,7 @@ modify this GNU manual.''
 
 @contents
 
address@hidden Top
address@hidden 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
 
address@hidden  Overview
address@hidden  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
 
address@hidden  Quick start
address@hidden  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.
 
address@hidden Commands
address@hidden 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
 
address@hidden Key management
address@hidden 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 
address@hidden, it
 also delete the secret keys.
 @end deffn
 
address@hidden Cryptographic operations on regions
address@hidden 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
 
address@hidden Cryptographic operations on files
address@hidden 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
 
address@hidden Dired integration
address@hidden 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
 
address@hidden Mail-mode integration
address@hidden 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
 
address@hidden Encrypting/decrypting gpg files
address@hidden 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 address@hidden, disable auto-saving when opening an 
encrypted file.
 The default value is @code{t}.
 @end defvar
 
address@hidden Caching Passphrases
address@hidden GnuPG version compatibility, Caching Passphrases, Commands, Top
address@hidden 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.
+
address@hidden
address@hidden
+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.
+
address@hidden
+2.1 uses a fixed Unix domain socket for gpg-agent, and ignores the
address@hidden environment variable, used by 2.0 and 1.4.
+
address@hidden
+2.1 (2.1.5 or later) has a mechanism to direct the Pinentry password
+prompt to the Emacs address@hidden enable this feature, add
address@hidden 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.
address@hidden itemize
+
address@hidden 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 address@hidden
+version compatibility}, encryption method (symmetric or public key),
+and whether or not you want to use gpg-agent.  Here are some
+questions:
 
 @enumerate
address@hidden Do you use GnuPG version 2 instead of GnuPG version 1?
address@hidden 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}.
 
address@hidden Bug Reports
address@hidden 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.
 
address@hidden GNU Free Documentation License
address@hidden GNU Free Documentation License, Key Index, Bug Reports, Top
 @appendix GNU Free Documentation License
 @include doclicense.texi
 
address@hidden Key Index
address@hidden Key Index, Function Index, GNU Free Documentation License, Top
 @unnumbered Key Index
 @printindex ky
 
address@hidden Function Index
address@hidden Function Index, Variable Index, Key Index, Top
 @unnumbered Function Index
 @printindex fn
 
address@hidden Variable Index
address@hidden Variable Index,  , Function Index, Top
 @unnumbered Variable Index
 @printindex vr