doc update

2 files changed, 20 insertions, 9 deletions

diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index fb4b2f9e5d..1363124e54 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -196,6 +196,10 @@ int main()
 @}
 @end example
 
+Note that @funcref{gnutls_global_init} is itself not thread safe. It is also not recommended
+to initialize it on every available thread, but if need to, it should be protected using
+mutex locks.
+
 @showfuncdesc{gnutls_global_set_mutex}
 
 @node Callback functions
@@ -246,9 +250,11 @@ library.
 
 GnuTLS must be initialized before it can be used.  The library is
 initialized by calling @funcref{gnutls_global_init}. That call
-typically enables CPU-specific acceleration, and performs any requires
-precalculations needed by the library. The resources
-allocated by the initialization process can be released if the
+typically enables CPU-specific acceleration, performs any required
+precalculations needed, and initializes subsystems that could be
+used later (e.g., PKCS #11 -- see @ref{PKCS11 Initialization}).
+
+The resources allocated by the initialization process can be released if the
 application no longer has a need to call GnuTLS functions, this is
 done by calling @funcref{gnutls_global_deinit}.
 
diff --git a/doc/cha-tokens.texi b/doc/cha-tokens.texi
index 40ad477d9f..e4b04dd90e 100644
--- a/doc/cha-tokens.texi
+++ b/doc/cha-tokens.texi
@@ -200,9 +200,12 @@ system, being the @acronym{Gnome Keyring}.
 
 @node PKCS11 Initialization
 @subsection Initialization
-To allow all the  @acronym{GnuTLS} applications to access @acronym{PKCS} #11 tokens
-you can use a configuration per module, stored in @code{/etc/pkcs11/modules/}. 
-These are the configuration files of @acronym{p11-kit}@footnote{@url{http://p11-glue.freedesktop.org/}}.
+To allow all @acronym{GnuTLS} applications to transparently access smard cards
+and tokens, @acronym{PKCS} #11 is automatically initialized during the global 
+initialization (see @funcref{gnutls_global_init}). The initialization function, to select
+which modules to load reads certain module configuration files.
+Those are stored in @code{/etc/pkcs11/modules/} and 
+are the configuration files of @acronym{p11-kit}@footnote{@url{http://p11-glue.freedesktop.org/}}.
 For example a file that will load the @acronym{OpenSC} module, could be named
 @code{/etc/pkcs11/modules/opensc} and contain the following:
 
@@ -210,15 +213,17 @@ For example a file that will load the @acronym{OpenSC} module, could be named
 module: /usr/lib/opensc-pkcs11.so
 @end example
 
-If you use this file, then there is no need for other initialization in
+If you use these configuration files, then there is no need for other initialization in
 @acronym{GnuTLS}, except for the PIN and token functions (see next section).  
 In several cases, however, it is desirable to limit badly behaving modules 
 (e.g., modules that add an unacceptable delay on initialization)
 to single applications. That can be done using the ``enable-in:'' option
 followed by the base name of applications that this module should be used.
 
-In all cases, you may also manually initialize the PKCS #11 subsystem if the 
-default settings are not desirable.
+In all cases, you can also manually initialize the PKCS #11 subsystem if the 
+default settings are not desirable. To completely disable PKCS #11 support you
+need to call @funcref{gnutls_pkcs11_init} with the flag @code{GNUTLS_PKCS11_FLAG_MANUAL}
+prior to @funcref{gnutls_global_init}.
 
 @showfuncdesc{gnutls_pkcs11_init}