+# While the output of gnulib-tool is "include"-able if the --makefile-name
+# option is used, it is still not suitable for non-recursive use for a couple
+# reasons; chief among them is that filenames are not relative to the top
+# source directory.
+#
+# This script postprocesses the gnulib-tool output to produce something
+# that is intended to be suitable for inclusion into such non-recursive
+# build environments. Since the integration involves both configure.ac
+# and Makefile.am, the output must be included into _both_. Supposing
+# the output is written to lib/gnulib.mk, you would add:
+#
+# m4_include([lib/gnulib.mk]) # to configure.ac, after any call to gl_INIT
+# include $(top_srcdir)/lib/gnulib.mk # to Makefile.am
+#
+# You must also arrange for the Gnulib-generated header files to be built
+# before the object files which depend on them; the most robust way to do
+# this is by explicit prerequisites, for example:
+#
+# bin_PROGRAMS = foo
+# $(foo_OBJECTS): $(gnulib_headers)
+#
+# The $(gnulib_headers) variable will expand to GNU-make order-only
+# prerequisites when available, avoiding spurious incremental rebuilds when
+# unused headers are changed. If this feature is not available, it will
+# expand to ordinary prerequisites. It is therefore only appropriate for
+# use in target prerequisites; the $(gnulib_raw_headers) variable may be
+# used in other contexts when only the list of header files is required.
+#
+# This script also provides machinery for Gnulib symbol renaming via the
+# glconfig.mk Makefile.am snippet; use of this feature is optional.
+#
+# Most of the specific transformations are documented below.