doc: Update documentation for gpgme.pc and pkg-config.

--

GnuPG-bug-id: 6274
Signed-off-by: NIIBE Yutaka <gniibe@fsij.org>

doc/gpgme.texi

@@ -421,18 +421,28 @@ directory in which the header file is located to the compilers include
 file search path (via the @option{-I} option).
 
 However, the path to the include file is determined at the time the
-source is configured.  To solve this problem, gpgme ships with a small
+source is configured.  To solve this problem, gpgme ships with
-helper program @command{gpgme-config} that knows about the path to the
+@code{gpgme.pc} file, that knows about the path to the include file
-include file and other configuration options.  The options that need
+and other configuration options.  The command, @command{pkg-config},
-to be added to the compiler invocation at compile time are output by
+can be used to handle information with @code{gpgme.pc} file.  In an
-the @option{--cflags} option to @command{gpgme-config}.  The following
+environment which doesn't have @command{pkg-config} (like the one in
-example shows how it can be used at the command line:
+early stage of OS bootstrap), for Automake, you can use
+@code{gpgme.m4} which invokes @command{gpgrt-config} with
+@code{gpgme.pc}.  (In the past, gpgme used to ship with a small helper
+program @command{gpgme-config}.  This functionality of
+@command{gpgme-config} is replaced by @command{pkg-config} with
+@code{gpgme.pc} file.)
+
+The options that need to be added to the compiler invocation at
+compile time are output by the @option{--cflags} option to
+@command{pkg-config gpgme}.  The following example shows how it can be
+used at the command line:
 
 @example
-gcc -c foo.c `gpgme-config --cflags`
+gcc -c foo.c `pkg-config --cflags gpgme`
 @end example
 
-Adding the output of @samp{gpgme-config --cflags} to the compiler
+Adding the output of @samp{pkg-config --cflags gpgme} to the compiler
 command line will ensure that the compiler can find the
 @acronym{GPGME} header file.
 
@@ -440,36 +450,39 @@ A similar problem occurs when linking the program with the library.
 Again, the compiler has to find the library files.  For this to work,
 the path to the library files has to be added to the library search
 path (via the @option{-L} option).  For this, the option
-@option{--libs} to @command{gpgme-config} can be used.  For
+@option{--libs} to @command{pkg-config gpgme} can be used.  For
 convenience, this option also outputs all other options that are
 required to link the program with @acronym{GPGME} (in particular, the
 @samp{-lgpgme} option).  The example shows how to link @file{foo.o}
 with the @acronym{GPGME} library to a program @command{foo}.
 
 @example
-gcc -o foo foo.o `gpgme-config --libs`
+gcc -o foo foo.o `pkg-config --libs gpgme`
 @end example
 
 Of course you can also combine both examples to a single command by
-specifying both options to @command{gpgme-config}:
+specifying both options to @command{pkg-config gpgme}:
 
 @example
-gcc -o foo foo.c `gpgme-config --cflags --libs`
+gcc -o foo foo.c `pkg-config --cflags --libs gpgme`
-@end example
-
-If you need to detect the installed language bindings you can use list
-them using:
-
-@example
-gpgme-config --print-lang
-@end example
-
-or test for the availability using
-
-@example
-gpgme-config --have-lang=python && echo 'Bindings for Pythons available'
 @end example
 
+@c
+@c Feature not available by pkg-config/gpgrt-config
+@c
+@c If you need to detect the installed language bindings you can use list
+@c them using:
+@c
+@c @example
+@c gpgme-config --print-lang
+@c @end example
+@c
+@c or test for the availability using
+@c
+@c @example
+@c gpgme-config --have-lang=python && echo 'Bindings for Pythons available'
+@c @end example
+@c
 
 @node Largefile Support (LFS)
 @section Largefile Support (LFS)
@@ -578,7 +591,7 @@ mode (@code{_LARGEFILE64_SOURCE}).
 
 It is much easier if you use GNU Automake instead of writing your own
 Makefiles.  If you do that you do not have to worry about finding and
-invoking the @command{gpgme-config} script at all.  @acronym{GPGME}
+invoking the @command{pkg-config} script at all.  @acronym{GPGME}
 provides an extension to Automake that does all the work for you.
 
 @c A simple macro for optional variables.
@@ -586,20 +599,28 @@ provides an extension to Automake that does all the work for you.
 @r{[}@var{\varname\}@r{]}
 @end macro
 @defmac AM_PATH_GPGME (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found})
-@defmacx AM_PATH_GPGME_PTH (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found})
-@defmacx AM_PATH_GPGME_PTHREAD (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found})
 Check whether @acronym{GPGME} (at least version @var{minimum-version},
 if given) exists on the host system.  If it is found, execute
 @var{action-if-found}, otherwise do @var{action-if-not-found}, if
 given.
 
+This macro locates for @code{gpgme.pc}, with cross-compile support.
+
 Additionally, the function defines @code{GPGME_CFLAGS} to the flags
 needed for compilation of the program to find the @file{gpgme.h}
 header file, and @code{GPGME_LIBS} to the linker flags needed to link
-the program to the @acronym{GPGME} library.  If the used helper script
+the program to the @acronym{GPGME} library.
-does not match the target type you are building for a warning is
+@c
-printed and the string @code{libgcrypt} is appended to the variable
+@c If the used helper script does not match the target type you are
-@code{gpg_config_script_warn}.
+@c building for a warning is printed and the string @code{gpgme} is
+@c appended to the variable @code{gpg_config_script_warn}.
+@c@c@c@c@c@c@c@c
+@c ^-- About this statement.
+@c In the past, this might happens, when it was configured by
+@c --with-*-prefix options, and it located the helper script for
+@c other target.  Cross-build by gpgrt-config has been improved
+@c (in different way), so it's not relevant now.
+@c
 
 @code{AM_PATH_GPGME_PTHREAD} checks for the version of @acronym{GPGME}
 that can be used with the native pthread implementation, and defines
@@ -607,15 +628,6 @@ that can be used with the native pthread implementation, and defines
 version 1.8.0 this is no longer required to GPGME_PTHREAD as
 @acronym{GPGME} itself is thread safe.
 
-This macro searches for @command{gpgme-config} along the PATH.  If
-you are cross-compiling, it is useful to set the environment variable
-@code{SYSROOT} to the top directory of your target.  The macro will
-then first look for the helper program in the @file{bin} directory
-below that top directory.  An absolute directory name must be used for
-@code{SYSROOT}.  Finally, if the configure command line option
-@code{--with-gpgme-prefix} is used, only its value is used for the top
-directory below which the helper script is expected.
-
 @end defmac
 
 You can use the defined Autoconf variables like this in your
@@ -632,9 +644,8 @@ LDADD = $(GPGME_LIBS)
 @cindex libtool
 
 The easiest way is to just use GNU Libtool.  If you use libtool, and
-link to @code{libgpgme.la}, @code{libgpgme-pth.la} or
+link to @code{libgpgme.la}, everything will be done automatically by
-@code{libgpgme-pthread.la} respectively, everything will be done
+Libtool.
-automatically by Libtool.
 
 
 @node Library Version Check