From f548ca97ad1fa83edb8140226ca620cc4c8c0db9 Mon Sep 17 00:00:00 2001
From: Werner Koch <wk@gnupg.org>
Date: Mon, 2 Mar 2009 11:53:32 +0000
Subject: [PATCH] Modernized gpg-agent startup instructions

---
 common/homedir.c   |  2 +-
 doc/ChangeLog      |  4 ++++
 doc/gpg-agent.texi | 33 +++++++++++++++++++++++----------
 3 files changed, 28 insertions(+), 11 deletions(-)

diff --git a/common/homedir.c b/common/homedir.c
index 74f3a0d1f..5f2e31e0a 100644
--- a/common/homedir.c
+++ b/common/homedir.c
@@ -86,7 +86,7 @@ w32_shgetfolderpath (HWND a, int b, HANDLE c, DWORD d, LPSTR e)
 
 /* Get the standard home directory.  In general this function should
    not be used as it does not consider a registry value (under W32) or
-   the GNUPGHOME encironment variable.  It is better to use
+   the GNUPGHOME environment variable.  It is better to use
    default_homedir(). */
 const char *
 standard_homedir (void)
diff --git a/doc/ChangeLog b/doc/ChangeLog
index 2bffa5faf..53d7faf27 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,7 @@
+2009-03-02  Werner Koch  <wk@g10code.com>
+
+	* gpg-agent.texi (Invoking GPG-AGENT): Modernized instructions.
+
 2009-01-12  Werner Koch  <wk@g10code.com>
 
 	* faq.raw: Fix bug reorting address.
diff --git a/doc/gpg-agent.texi b/doc/gpg-agent.texi
index 2900154a9..af30a2390 100644
--- a/doc/gpg-agent.texi
+++ b/doc/gpg-agent.texi
@@ -61,23 +61,36 @@ to run multiple instance of the @command{gpg-agent}, so you should make
 sure that only one is running: @command{gpg-agent} uses an environment
 variable to inform clients about the communication parameters. You can
 write the content of this environment variable to a file so that you can
-test for a running agent.  This short script may do the job:
+test for a running agent.  Here is an example using Bourne shell synax:
 
 @smallexample
-if test -f $HOME/.gpg-agent-info && \
-   kill -0 $(cut -d: -f 2 $HOME/.gpg-agent-info) 2>/dev/null; then
-     GPG_AGENT_INFO=$(cat $HOME/.gpg-agent-info)
-     export GPG_AGENT_INFO   
-else
-     eval $(gpg-agent --daemon)
-     echo $GPG_AGENT_INFO >$HOME/.gpg-agent-info
+gpg-agent --daemon --enable-ssh-support \
+          --write-env-file "$@{HOME@}/.gpg-agent-info"
+@end smallexample
+
+This code should only be run once per user session to initially fire up
+the agent.  In the example the optional support for the included Secure
+Shell agent is enabled and the information about the agent is written to
+a file in the HOME directory.  Note that by running gpg-agent without
+arguments you may test whether an agent is already running; however such
+a test may lead to a race condition, thus it is not suggested.
+
+@noindent
+The second script needs to be run for each interactive session:
+
+@smallexample
+if [ -f "$@{HOME@}/.gpg-agent-info" ]; then
+  . "$@{HOME@}/.gpg-agent-info"
+  export GPG_AGENT_INFO
+  export SSH_AUTH_SOCK
+  export SSH_AGENT_PID
 fi
 @end smallexample
 
 @noindent
-Note that the new option @option{--write-env-file} may be used instead.
+It reads the data out of the file and exports the variables.  If you
+don't use Secure Shell, you don't need the last two export statements.
  
-
 @noindent
 You should always add the following lines to your @code{.bashrc} or
 whatever initialization file is used for all shell invocations: