doc update

diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index fb4b2f9e5d12a679da92bdf773654d93cf6fdd65..1363124e542267ee274bb3bf92ca7b7218e0cd67 100644 (file)
--- 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 40ad477d9f8298d3a5408eef6341f3afcd2d57fb..e4b04dd90e3a1ae713c2811ab747b7bad9778600 100644 (file)
--- 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}