Re: Documenting gpg-agent

[Chong Yidong]

Richard Stallman <address@hidden> writes:

>     ! When using GnuPG the additional use of the gpg-agent (@pxref{Caching
>     ! passphrase}) is highly recommended, as it provides the most secure way
>     ! for input and caching of passphrases.  Please refer to the documentation
>     ! of GnuPG for details on installation and usage.
>
> This isn't sufficient, because
>
> 1. It should have an Info xref to the proper node in the other manual.
> "Please refer to the documentation of GnuPG" is not sufficient.
>
> 2. Just an xref is not enough.  This needs to actually explain the
> simple usage of gpg-agent.
>
> 3. If this is the preferred method, to avoid a security hole,
> then we should remove or deprecate other methods.

How aboout this?

*** emacs/man/pgg.texi.~1.14.~  2006-12-17 18:16:25.000000000 -0500
--- emacs/man/pgg.texi  2006-12-23 20:04:50.000000000 -0500
***************
*** 74,88 ****
  This document assumes that you have already obtained and installed them
  and that you are familiar with its basic functions.
  
! By default, PGG uses GnuPG, but Pretty Good Privacy version 2 or version
! 5 are also supported.  If you are new to such a system, I recommend that
! you should look over the GNU Privacy Handbook (GPH) which is available
! at @uref{http://www.gnupg.org/documentation/}.
! 
! When using GnuPG the additional use of the gpg-agent (@pxref{Caching
! passphrase}) is highly recommended, as it provides the most secure way
! for input and caching of passphrases.  Please refer to the documentation
! of GnuPG for details on installation and usage.
  
  @node How to use
  @chapter How to use
--- 74,92 ----
  This document assumes that you have already obtained and installed them
  and that you are familiar with its basic functions.
  
! By default, PGG uses GnuPG.  If you are new to such a system, I
! recommend that you should look over the GNU Privacy Handbook (GPH)
! which is available at @uref{http://www.gnupg.org/documentation/}.
! 
! When using GnuPG, we recommend the use of the @code{gpg-agent}
! program, which is distributed with versions 2.0 and later of GnuPG.
! This is a daemon to manage private keys independently from any
! protocol, and provides the most secure way to input and cache your
! passphrases (@pxref{Caching passphrase}).  By default, PGG will
! attempt to use gpg-agent if it is running.  @xref{Invoking
! GPG-AGENT,,,gnupg,Using the GNU Privacy Guard}.
! 
! PGG also supports Pretty Good Privacy version 2 or version 5.
  
  @node How to use
  @chapter How to use
***************
*** 243,250 ****
  When using GnuPG (gpg) as PGP scheme you can use @code{gpg-agent} for
  address@hidden @code{gpg-agent} does not cache passphrases
  but private keys.  On the other hand, from a users point of view this
! technical difference isn't visible.}.  If address@hidden try to use a
! running @code{gpg-agent}.  It defaults to @code{nil}.
  @end defvar
  
  @node Default user identity
--- 247,254 ----
  When using GnuPG (gpg) as PGP scheme you can use @code{gpg-agent} for
  address@hidden @code{gpg-agent} does not cache passphrases
  but private keys.  On the other hand, from a users point of view this
! technical difference isn't visible.}.  It defaults to @code{t}.
! Setting this to @code{nil} is not recommended.
  @end defvar
  
  @node Default user identity