diff --git a/doc/examples/gpgconf.conf b/doc/examples/gpgconf.conf
index 95e463b6e..a61d4d453 100644
--- a/doc/examples/gpgconf.conf
+++ b/doc/examples/gpgconf.conf
@@ -5,6 +5,10 @@
 # defaults in gpgconf and to enforce certain values for the various
 # GnuPG related configuration files.
 #
+# NOTE: This is a legacy mechanism.  The modern way is to use global
+#       configuration files like /etc/gnupg/gpg.conf which are more
+#       flexible and better integrated into the configuration system.
+#
 # Empty lines and comment lines, indicated by a hash mark as first non
 # white space character, are ignored.  The line is separated by white
 # space into fields. The first field is used to match the user or
@@ -56,7 +60,3 @@
 # "enable-ocsp" is put into the config file of gpgsm.  The latter may
 # be changed by any user.
 #-------------------------------------------------------------------
-
-
-
-
diff --git a/doc/tools.texi b/doc/tools.texi
index 208c07cb9..4fff44fad 100644
--- a/doc/tools.texi
+++ b/doc/tools.texi
@@ -298,6 +298,8 @@ shall go into the respective configuration file.
 @item --apply-defaults
 Update all configuration files with values taken from the global
 configuration file (usually @file{/etc/gnupg/gpgconf.conf}).
+Note: This is a legacy mechanism.  Please use global configuraion
+files instead.
 
 @item --list-dirs [@var{names}]
 @itemx -L
@@ -952,8 +954,12 @@ effect.
 @node Listing global options
 @subsection Listing global options
 
-Sometimes it is useful for applications to look at the global options
-file @file{gpgconf.conf}.
+Some legacy applications look at the global configuration file for the
+gpgconf tool itself; this is the file @file{gpgconf.conf}.  Modern
+applications should not use it but use per component global
+configuration files which are more flexible than the
+@file{gpgconf.conf}.  Using both files is not suggested.
+
 The colon separated listing format is record oriented and uses the first
 field to identify the record type:
 
@@ -1094,8 +1100,10 @@ More fields may be added in future to the output.
 @item /etc/gnupg/gpgconf.conf
 @cindex gpgconf.conf
   If this file exists, it is processed as a global configuration file.
-  A commented example can be found in the @file{examples} directory of
-  the distribution.
+  This is a legacy mechanism which should not be used tigether with
+  the modern global per component configuration files.  A commented
+  example can be found in the @file{examples} directory of the
+  distribution.
 
 @item @var{GNUPGHOME}/swdb.lst
 @cindex swdb.lst
@@ -1134,6 +1142,9 @@ More fields may be added in future to the output.
 @end ifset
 
 @mansect description
+This is a legacy script.  Modern application should use the per
+component global configuration files under @file{/etc/gnupg/}.
+
 This script is a wrapper around @command{gpgconf} to run it with the
 command @code{--apply-defaults} for all real users with an existing
 GnuPG home directory.  Admins might want to use this script to update he