Further documentation improvements.

Improve the module's m4 file generated by duneproject

[[Imported from SVN: r5828]]

bin/dunecontrol

@@ -660,6 +660,8 @@ while test $# -gt 0; do
       echo "    for $name $version $maintainer"
       echo "        requires $requires"
       cat > $fname <<EOF
+# dependencies.m4 generated by dunecontrol
+
 m4_define([DUNE_AC_INIT],[
   AC_INIT([$name], [$version], [$maintainer])
   AM_INIT_AUTOMAKE([foreign 1.5 tar-pax])

bin/duneproject

@@ -583,10 +583,23 @@ CC_DELIM
 M4_MODULE=`echo $MODULE | tr '[a-z-]' '[A-Z_]'`
 echo "- $PROJECT/m4/$MODULE.m4"
 cat> "$PROJECT/m4/$MODULE.m4" << CC_DELIM
-# Additional checks needed to build the module
+dnl -*- autoconf -*-
+# Macros needed to find $MODULE and dependent libraries.  They are called by
+# the macros in \${top_src_dir}/dependencies.m4, which is generated by
+# "dunecontrol autogen"
+
+# Additional checks needed to build $MODULE
+# This macro should be invoked by every module which depends on $MODULE, as
+# well as by $MODULE itself
 AC_DEFUN([${M4_MODULE}_CHECKS])
-# Additional checks needed to find the module
-AC_DEFUN([${M4_MODULE}_CHECK_MODULE])
+
+# Additional checks needed to find $MODULE
+# This macro should be invoked by every module which depends on $MODULE, but
+# not by $MODULE itself
+AC_DEFUN([${M4_MODULE}_CHECK_MODULE],
+[
+  DUNE_CHECK_MODULES([$MODULE],[$NAME/$NAME.hh])
+])
 CC_DELIM
 
 

m4/dune.m4

@@ -41,14 +41,14 @@ m4_define([_dune_sub_version],"`echo $1 | $AWK -F. -v FIELD=$2 '{ print int($FIE
 # VERSION Version of the module.  May contain shell variables.  Numbers
 #         seperated by ".".
 #
-# In the following, module is NAME with any "-" replaced by "_" and MODULE is
-# the uppercase version of module.
+# In the following, {MODULE} is the uppercase version of {NAME} with any "-"
+# replaced by "_".
 #
 # configure/shell variables and preprocessor defines:
-#   MODULE_VERSION (complete version, same as VERSION)
-#   MODULE_VERSION_MAJOR (first component of VERSION)
-#   MODULE_VERSION_MINOR (second component of VERSION)
-#   MODULE_VERSION_REVISION (third component of VERSION)
+#   {MODULE}_VERSION (complete version, same as {VERSION})
+#   {MODULE}_VERSION_MAJOR (first component of {VERSION})
+#   {MODULE}_VERSION_MINOR (second component of {VERSION})
+#   {MODULE}_VERSION_REVISION (third component of {VERSION})
 AC_DEFUN([DUNE_PARSE_MODULE_VERSION],[
   AC_REQUIRE([AC_PROG_AWK])
 
@@ -75,64 +75,73 @@ AC_DEFUN([DUNE_PARSE_MODULE_VERSION],[
 
 # DUNE_CHECK_MODULES(NAME, HEADER, SYMBOL)
 #
+# Generic check for dune modules.  This macro should not be used directly, but
+# in the modules m4/{module}.m4 in the {MODULE}_CHECK_MODULE macro.  The
+# {MODULE}_CHECK_MODULE macro knows the parameters to call this
+# DUNE_CHECK_MODULES macro with, and it does not take any parameters itself,
+# so it may be used with AC_REQUIRE.
+#
 # NAME   Name of the module, lowercase with dashes (like "dune-common").  The
 #        value must be known when autoconf runs, so shell variables in the
 #        value are not permissible.
 #
-# HEADER Header to check for.  The check will really be for <dune/HEADER>, so
-#        the header must reside within a directory called "dune".
+# HEADER Header to check for.  The check will really be for <dune/{HEADER}>,
+#        so the header must reside within a directory called "dune".
 #
 # SYMBOL Symbol to check for in the module's library.  If this argument is
 #        empty or missing, it is assumed that the module does not provide a
 #        library.  The value must be known when autoconf runs, so shell
-#        variables in the value are not permissible.  The name of the library
-#        is assumed to be the same as the module name, with any occurance of
-#        "-" removed.  The path of the library is obtained from pkgconfig for
-#        installed modules, or assumed to be the directory "lib" within the
-#        modules root for non-installed modules.
+#        variables in the value are not permissible.  This value is actually
+#        handed to AC_TRY_LINK unchanged as the FUNCTION-BODY argument, so it
+#        may contain more complex stuff than a simple symbol.
+#
+#        The name of the library is assumed to be the same as the module name,
+#        with any occurance of "-" removed.  The path of the library is
+#        obtained from pkgconfig for installed modules, or assumed to be the
+#        directory "lib" within the modules root for non-installed modules.
 #
-# In the following, module is NAME with any "-" replaced by "_" and MODULE is
-# the uppercase version of module.
+# In the following, {module} is {NAME} with any "-" replaced by "_" and
+# {MODULE} is the uppercase version of {module}.
 #
 # configure options:
-#   --with-NAME
+#   --with-{NAME}
 #
 # configure/shell variables:
-#   MODULE_CPPFLAGS
-#   MODULE_ROOT
-#   MODULE_LDFLAGS
-#   MODULE_LIBS
-#   HAVE_MODULE (1 or 0)
-#   with_module ("yes" or "no")
+#   {MODULE}_CPPFLAGS
+#   {MODULE}_ROOT
+#   {MODULE}_LDFLAGS
+#   {MODULE}_LIBS
+#   HAVE_{MODULE} (1 or 0)
+#   with_{module} ("yes" or "no")
 #   DUNE_CPPFLAGS (adds the modules values here)
 #   DUNE_LDFLAGS (adds the modules values here)
 #   DUNE_LIBS (adds the modules values here)
 #   DUNE_PKG_CPPFLAGS (deprecated, adds the modules values here)
 #   DUNE_PKG_LDFLAGS (deprecated, adds the modules values here)
 #   DUNE_PKG_LIBS (deprecated, adds the modules values here)
-#   MODULE_VERSION
-#   MODULE_VERSION_MAJOR
-#   MODULE_VERSION_MINOR
-#   MODULE_VERSION_REVISION
+#   {MODULE}_VERSION
+#   {MODULE}_VERSION_MAJOR
+#   {MODULE}_VERSION_MINOR
+#   {MODULE}_VERSION_REVISION
 #
 # configure substitutions/makefile variables:
-#   MODULE_CPPFLAGS
-#   MODULE_LDFLAGS
-#   MODULE_LIBS
-#   MODULE_ROOT
+#   {MODULE}_CPPFLAGS
+#   {MODULE}_LDFLAGS
+#   {MODULE}_LIBS
+#   {MODULE}_ROOT
 #   DUNE_CPPFLAGS
 #   DUNE_LDFLAGS
 #   DUNE_LIBS
 #
 # preprocessor defines:
-#   HAVE_MODULE (1 or undefined)
-#   MODULE_VERSION
-#   MODULE_VERSION_MAJOR
-#   MODULE_VERSION_MINOR
-#   MODULE_VERSION_REVISION
+#   HAVE_{MODULE} (1 or undefined)
+#   {MODULE}_VERSION
+#   {MODULE}_VERSION_MAJOR
+#   {MODULE}_VERSION_MINOR
+#   {MODULE}_VERSION_REVISION
 #
 # automake conditionals:
-#   HAVE_MODULE
+#   HAVE_{MODULE}
 AC_DEFUN([DUNE_CHECK_MODULES],[
   AC_REQUIRE([AC_PROG_CXX])
   AC_REQUIRE([AC_PROG_CXXCPP])