Add global flags disable-gpgconf, gpgconf-name, and gpg-name.
[gpgme.git] / doc / gpgme.texi
index 18b3c94..3f31492 100644 (file)
@@ -1,5 +1,5 @@
-\input texinfo                   @c -*- mode: texinfo; coding: latin-1; -*-
-@documentencoding ISO-8859-1
+\input texinfo                   @c -*- mode: texinfo; coding: utf-8; -*-
+@documentencoding UTF-8
 @setfilename gpgme.info
 @settitle The `GnuPG Made Easy' Reference Manual
 
@@ -14,7 +14,7 @@
 
 @copying
 Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007,
-2008, 2010, 2012, 2013 g10 Code GmbH.
+2008, 2010, 2012, 2013, 2014 g10 Code GmbH.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -72,7 +72,7 @@ This is Edition @value{EDITION}, last updated @value{UPDATED}, of
 @center for version @value{VERSION}
 @page
 @vskip 0pt plus 1filll
-Published by g10 Code GmbH@* Hüttenstr. 61@* 40699 Erkrath, Germany
+Published by g10 Code GmbH@* Hüttenstr. 61@* 40699 Erkrath, Germany
 
 @insertcopying
 @end titlepage
@@ -648,14 +648,39 @@ does not return a detailed error code).
 On some systems it is not easy to set environment variables and thus
 hard to use @acronym{GPGME}'s internal trace facility for debugging.
 This function has been introduced as an alternative way to enable
-debugging.  It is important to assure that only one thread accesses
-@acronym{GPGME} functions between a call to this function and after
-the return from the call to @code{gpgme_check_version}.
-
-To enable debugging, you need to call this function as early as
-possible --- even before @code{gpgme_check_version} --- with the
-string ``debug'' for @var{name} and @var{value} identical to the value
-used with the environment variable @code{GPGME_DEBUG}.
+debugging and for a couple of other rarely used tweaks.  It is
+important to assure that only one thread accesses @acronym{GPGME}
+functions between a call to this function and after the return from
+the call to @code{gpgme_check_version}.
+
+All currently supported features require that this function is called
+as early as possible --- even before @code{gpgme_check_version}.  The
+features are identified by the following values for @var{name}:
+
+@table @code
+@item "debug"
+To enable debugging use the string ``debug'' for @var{name} and
+@var{value} identical to the value used with the environment variable
+@code{GPGME_DEBUG}.
+
+@item "disable-gpgconf"
+Using this feature with any @var{value} disables the detection of the
+gpgconf program and thus forces GPGME to fallback into the simple
+OpenPGP only mode.  It may be used to force the use of GnuPG-1 on
+systems which have both GPG versions installed.  Note that in general
+the use of @code{gpgme_set_engine_info} is a better way to select a
+specific engine version.
+
+@item "gpgconf-name"
+@itemx "gpg-name"
+Set the name of the gpgconf respective gpg binary.  The defaults are
+@code{GNU/GnuPG/gpgconf} and @code{GNU/GnuPG/gpg}.  Under Unix the
+leading directory part is ignored.  Under Windows the leading
+directory part is used as the default installation directory; the
+@code{.exe} suffix is added by GPGME.  Use forward slashed even under
+Windows.
+
+@end table
 
 This function returns @code{0} on success.  In contrast to other
 functions the non-zero return value on failure does not convey any