X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/df5725c5fbcc9b306ebba5bf51870eba4ae2cb0e..5a7f4c1bf2b8a1ef30810640bc255494dd3b957b:/man/pgg.texi

diff --git a/man/pgg.texi b/man/pgg.texi
index b3829e5fa8..23bcd5cbb1 100644
--- a/man/pgg.texi
+++ b/man/pgg.texi
@@ -6,10 +6,10 @@
 
 
 @copying
-This file describes the PGG.
+This file describes PGG, an Emacs interface to various PGP implementations.
 
-Copyright (C) 2003, 2004, 2005 Free Software Foundation, Inc.
-Copyright (C) 2001 Daiki Ueno.
+Copyright @copyright{} 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
+Copyright @copyright{} 2001 Daiki Ueno.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -17,7 +17,7 @@ under the terms of the GNU Free Documentation License, Version 1.2 or
 any later version published by the Free Software Foundation; with no
 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
 Texts.  A copy of the license is included in the section entitled ``GNU
-Free Documentation License''.
+Free Documentation License.''
 @end quotation
 @end copying
 
@@ -129,7 +129,7 @@ signer's public key, for example, the function @code{pgg-verify-region}
 fails immediately, but if the function had been called interactively, it
 would ask you to retrieve the signer's public key from the server.
 
-@deffn Command pgg-encrypt-region start end recipients &optional sign
+@deffn Command pgg-encrypt-region start end recipients &optional sign passphrase
 Encrypt the current region between @var{start} and @var{end} for
 @var{recipients}.  When the function were called interactively, you
 would be asked about the recipients.
@@ -138,36 +138,47 @@ If encryption is successful, it replaces the current region contents (in
 the accessible portion) with the resulting data.
 
 If optional argument @var{sign} is non-@code{nil}, the function is
-request to do a combined sign and encrypt.  This currently only work
-with GnuPG.
+request to do a combined sign and encrypt.  This currently is
+confirmed to work with GnuPG, but might not work with PGP or PGP5.
+
+If optional @var{passphrase} is @code{nil}, the passphrase will be
+obtained from the passphrase cache or user.
 @end deffn
 
-@deffn Command pgg-encrypt-symmetric-region start end
+@deffn Command pgg-encrypt-symmetric-region &optional start end passphrase
 Encrypt the current region between @var{start} and @var{end} using a
 symmetric cipher.  After invocation you are asked for a passphrase.
 
-This is currently only implemented for GnuPG.
+If optional @var{passphrase} is @code{nil}, the passphrase will be
+obtained from the passphrase cache or user.
+
+symmetric-cipher encryption is currently only implemented for GnuPG.
 @end deffn
 
-@deffn Command pgg-decrypt-region start end
+@deffn Command pgg-decrypt-region start end &optional passphrase
 Decrypt the current region between @var{start} and @var{end}.  If
 decryption is successful, it replaces the current region contents (in
 the accessible portion) with the resulting data.
+
+If optional @var{passphrase} is @code{nil}, the passphrase will be
+obtained from the passphrase cache or user.
 @end deffn
 
-@deffn Command pgg-sign-region start end &optional cleartext
+@deffn Command pgg-sign-region start end &optional cleartext passphrase
 Make the signature from text between @var{start} and @var{end}.  If the
 optional third argument @var{cleartext} is non-@code{nil}, or the
 function is called interactively, it does not create a detached
 signature.  In such a case, it replaces the current region contents (in
 the accessible portion) with the resulting data.
+
+If optional @var{passphrase} is @code{nil}, the passphrase will be
+obtained from the passphrase cache or user.
 @end deffn
 
 @deffn Command pgg-verify-region start end &optional signature fetch
 Verify the current region between @var{start} and @var{end}.  If the
-optional third argument @var{signature} is non-@code{nil}, or the function
-is called interactively, it is treated as the detached signature of the
-current region.
+optional third argument @var{signature} is non-@code{nil}, it is treated
+as the detached signature file of the current region.
 
 If the optional 4th argument @var{fetch} is non-@code{nil}, or the
 function is called interactively, we attempt to fetch the signer's
@@ -192,22 +203,18 @@ considerably.  For example, if you are using GnuPG, you know you can
 select cipher algorithm from 3DES, CAST5, BLOWFISH, and so on, but on
 the other hand the version 2 of PGP only supports IDEA.
 
-By default, if the variable @code{pgg-scheme} is not set, PGG searches the
-registered scheme for an implementation of the requested service
-associated with the named algorithm.  If there are no match, PGG uses
-@code{pgg-default-scheme}.  In other words, there are two options to
-control which command is used to process the incoming PGP armors.  One
-is for encrypting and signing, the other is for decrypting and
-verifying.
+Which implementation is used is controlled by the @code{pgg-scheme}
+variable.  If it is @code{nil} (the default), the value of the
+@code{pgg-default-scheme} variable will be used instead.
 
 @defvar pgg-scheme
-Force specify the scheme of PGP implementation for decrypting and verifying.
-The value can be @code{gpg}, @code{pgp}, and @code{pgp5}.
+Force specify the scheme of PGP implementation.  The value can be set to
+@code{gpg}, @code{pgp}, and @code{pgp5}.  The default is @code{nil}.
 @end defvar
 
 @defvar pgg-default-scheme
-Force specify the scheme of PGP implementation for encrypting and signing.
-The value can be @code{gpg}, @code{pgp}, and @code{pgp5}.
+The default scheme of PGP implementation.  The value should be one of
+@code{gpg}, @code{pgp}, and @code{pgp5}.  The default is @code{gpg}.
 @end defvar
 
 @node Caching passphrase
@@ -218,14 +225,23 @@ arrange the interaction, set the variable @code{pgg-read-passphrase}.
 
 @defvar pgg-cache-passphrase
 If non-@code{nil}, store passphrases.  The default value of this
-variable is @code{t}.  If you were worry about security issue, however,
-you could stop caching with setting it @code{nil}.
+variable is @code{t}.  If you are worried about security issues,
+however, you could stop the caching of passphrases by setting this
+variable to @code{nil}.
 @end defvar
 
 @defvar pgg-passphrase-cache-expiry
 Elapsed time for expiration in seconds.
 @end defvar
 
+@defvar pgg-gpg-use-agent
+When using GnuPG (gpg) as PGP scheme you can use @code{gpg-agent} for
+caching@footnote{Actually @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 non-@code{nil} try to use a
+running @code{gpg-agent}.  It defaults to @code{nil}.
+@end defvar
+
 @node Default user identity
 @section Default user identity
 
@@ -309,26 +325,26 @@ argument @var{type} is non-@code{nil}, it searches from the secret
 keyrings.
 @end deffn
 
-@deffn Method pgg-scheme-encrypt-region scheme start end recipients &optional sign
+@deffn Method pgg-scheme-encrypt-region scheme start end recipients &optional sign passphrase
 Encrypt the current region between @var{start} and @var{end} for
 @var{recipients}.  If @var{sign} is non-@code{nil}, do a combined sign
 and encrypt.  If encryption is successful, it returns @code{t},
 otherwise @code{nil}.
 @end deffn
 
-@deffn Method pgg-scheme-encrypt-symmetric-region scheme start end
+@deffn Method pgg-scheme-encrypt-symmetric-region scheme start end &optional passphrase
 Encrypt the current region between @var{start} and @var{end} using a
 symmetric cipher and a passphrases.  If encryption is successful, it
 returns @code{t}, otherwise @code{nil}.  This function is currently only
 implemented for GnuPG.
 @end deffn
 
-@deffn Method pgg-scheme-decrypt-region scheme start end
+@deffn Method pgg-scheme-decrypt-region scheme start end &optional passphrase
 Decrypt the current region between @var{start} and @var{end}.  If
 decryption is successful, it returns @code{t}, otherwise @code{nil}.
 @end deffn
 
-@deffn Method pgg-scheme-sign-region scheme start end &optional cleartext
+@deffn Method pgg-scheme-sign-region scheme start end &optional cleartext passphrase
 Make the signature from text between @var{start} and @var{end}.  If the
 optional third argument @var{cleartext} is non-@code{nil}, it does not
 create a detached signature.  If signing is successful, it returns