[librsvgmm] New macro to handle external documentation links

[Daniel Elstner <daniel src gnome org>]

commit ccc9637ca3204b16930336fe916d7e3be5e5da30
Author: Daniel Elstner <danielk openismus com>
Date:   Sun Aug 2 23:10:53 2009 +0200

    New macro to handle external documentation links
    
    * build/mm-doc.m4 (MM_ARG_WITH_TAGFILE_DOC): New macro to aid with
    the handling of references to external reference documentation, and
    Doxygen tag files in particular.  MM_ARG_WITH_TAGFILE_DOC() provides
    a sufficiently generic interface to allow C++ binding modules to
    declare documentation dependencies in configure.ac, with one macro
    invocation per dependency.  Everything beyond that is taken care of
    behind the scenes.  As much configuration data as possible is derived
    automatically from the environment.  Additionally, configure options
    are provided for manual configuration, which is particularly helpful
    for package maintainers.  See the documentation in the macro file for
    detailed information on usage and implementation.
    (MM_ARG_ENABLE_DOCUMENTATION): Remove the unnecessary flexibility to
    override the substitution variable and Automake conditional.  Thus,
    one layer of indirection through a helper macro could be removed.
    Additionally, define and clear the substitution variables which will
    be built incrementally with each MM_ARG_WITH_TAGFILE_DOC() call.

 build/mm-doc.m4 |  164 +++++++++++++++++++++++++++++++++++++++++-------------
 1 files changed, 124 insertions(+), 40 deletions(-)
---
diff --git a/build/mm-doc.m4 b/build/mm-doc.m4
index 5ac277b..f424e90 100644
--- a/build/mm-doc.m4
+++ b/build/mm-doc.m4
@@ -15,46 +15,9 @@
 ## You should have received a copy of the GNU General Public License
 ## along with mm-autofu.  If not, see <http://www.gnu.org/licenses/>.
 
-#serial 20090718
+#serial 20090725
 
-## _MM_ARG_ENABLE_DOCUMENTATION(variable)
-##
-m4_define([_MM_ARG_ENABLE_DOCUMENTATION],
-[dnl
-AC_ARG_VAR([PERL], [path to Perl interpreter])
-AC_PATH_PROG([PERL], [perl], [perl])[]dnl
-
-AC_ARG_VAR([DOT], [path to dot utility])
-AC_PATH_PROG([DOT], [dot], [dot])[]dnl
-
-AC_ARG_VAR([DOXYGEN], [path to Doxygen utility])
-AC_PATH_PROG([DOXYGEN], [doxygen], [doxygen])[]dnl
-
-AC_ARG_VAR([XSLTPROC], [path to xsltproc utility])
-AC_PATH_PROG([XSLTPROC], [xsltproc], [xsltproc])[]dnl
-
-AC_ARG_ENABLE([documentation],
-              [AS_HELP_STRING([--disable-documentation],
-                              [do not build or install the documentation])],
-              [$1=$enableval],
-              [$1=yes])[]dnl
-
-AS_IF([test "x[$]$1" != xno],
-  [AS_IF([test "x$PERL" = xperl], [AC_MSG_FAILURE([[
-*** Perl is required for installing the documentation.]])])
-
-  AS_IF([test "x$USE_MAINTAINER_MODE" != xno],
-  [  for mm_prog in "$DOT" "$DOXYGEN" "$XSLTPROC"
-    do
-      AS_CASE([$mm_prog], [dot|doxygen|xsltproc], [AC_MSG_FAILURE([[
-*** The documentation will be built in this configuration, but the
-*** required tool $mm_prog could not be found.]])])
-    done])[]dnl
-  ])
-AM_CONDITIONAL([$1], [test "x[$]$1" != xno])[]dnl
-])
-
-## MM_ARG_ENABLE_DOCUMENTATION([variable])
+## MM_ARG_ENABLE_DOCUMENTATION
 ##
 ## Provide the --disable-documentation configure option.  By default,
 ## the documentation will be included in the build.  If not explicitly
@@ -71,4 +34,125 @@ AM_CONDITIONAL([$1], [test "x[$]$1" != xno])[]dnl
 ## if not in maintainer mode.
 ##
 AC_DEFUN([MM_ARG_ENABLE_DOCUMENTATION],
-         [_MM_ARG_ENABLE_DOCUMENTATION(m4_default([$1], [ENABLE_DOCUMENTATION]))])
+[dnl
+AC_ARG_VAR([PERL], [path to Perl interpreter])[]dnl
+AC_ARG_VAR([DOT], [path to dot utility])[]dnl
+AC_ARG_VAR([DOXYGEN], [path to Doxygen utility])[]dnl
+AC_ARG_VAR([XSLTPROC], [path to xsltproc utility])[]dnl
+dnl
+AC_PATH_PROG([PERL], [perl], [perl])
+AC_PATH_PROG([DOT], [dot], [dot])
+AC_PATH_PROG([DOXYGEN], [doxygen], [doxygen])
+AC_PATH_PROG([XSLTPROC], [xsltproc], [xsltproc])
+dnl
+AC_ARG_ENABLE([documentation],
+              [AS_HELP_STRING([--disable-documentation],
+                              [do not build or install the documentation])],
+              [ENABLE_DOCUMENTATION=$enableval],
+              [ENABLE_DOCUMENTATION=yes])
+AS_IF([test "x$ENABLE_DOCUMENTATION" != xno],
+[
+  AS_IF([test "x$PERL" = xperl],
+        [AC_MSG_FAILURE([[Perl is required for installing the documentation.]])])
+
+  AS_IF([test "x$USE_MAINTAINER_MODE" != xno],
+  [
+    for mm_prog in "$DOT" "$DOXYGEN" "$XSLTPROC"
+    do
+      AS_CASE([$mm_prog], [[dot|doxygen|xsltproc]],
+              [AC_MSG_FAILURE([[The documentation will be built in this configuration,
+but the required tool $mm_prog could not be found.]])])
+    done
+  ])[]dnl
+])
+AM_CONDITIONAL([ENABLE_DOCUMENTATION], [test "x$ENABLE_DOCUMENTATION" != xno])
+AC_SUBST([DOXYGEN_TAGFILES], [[]])
+AC_SUBST([DOCINSTALL_FLAGS], [[]])[]dnl
+])
+
+## _MM_ARG_WITH_TAGFILE_DOC(option-basename, tagfilename, [module])
+##
+m4_define([_MM_ARG_WITH_TAGFILE_DOC],
+[dnl
+  AC_MSG_CHECKING([for $1 documentation])
+  AC_ARG_WITH([$1-doc],
+              [AS_HELP_STRING([[--with-$1-doc=[TAGFILE ]HTMLREFDIR]],
+                              [Link to external $1 documentation]m4_ifval([$3], [[ [auto]]]))],
+  [
+    mm_htmlrefdir=`[expr "@$withval" : ' * \(.*\)' 2>&]AS_MESSAGE_LOG_FD`
+    mm_tagname=`[expr "/$withval" : '[^ ]*[\\/]\([^\\/@]*\)@' 2>&]AS_MESSAGE_LOG_FD`
+    mm_tagpath=`[expr "X$withval" : 'X\([^ ]*\)@' 2>&]AS_MESSAGE_LOG_FD`
+    test "x$mm_tagname" != x || mm_tagname='$2'
+    test "x$mm_tagpath" != x || mm_tagpath=$mm_tagname[]dnl
+  ], [
+    mm_htmlrefdir=
+    mm_tagname='$2'
+    mm_tagpath='$2'dnl
+  ])
+m4_ifval([$3], [dnl
+  AS_IF([test "x$mm_htmlrefdir" = x],
+  [
+    mm_htmlrefdir=`$PKG_CONFIG --variable=htmlrefdir "$3" 2>&AS_MESSAGE_LOG_FD`dnl
+  ])
+  AS_CASE([$mm_htmlrefdir], [[http://*|https://*]], [mm_htmlrefpub=$mm_htmlrefdir],
+  [
+    mm_htmlrefpub=`$PKG_CONFIG --variable=htmlrefpub "$3" 2>&AS_MESSAGE_LOG_FD`
+    test "x$mm_htmlrefpub" != x || mm_htmlrefpub=$mm_htmlrefdir
+    test "x$mm_htmlrefdir" != x || mm_htmlrefdir=$mm_htmlrefpub
+  ])
+  AS_CASE([$mm_tagpath], [[*[\\/]*]],,
+  [
+    mm_doxytagfile=`$PKG_CONFIG --variable=doxytagfile "$3" 2>&AS_MESSAGE_LOG_FD`
+    test "x$mm_doxytagfile" = x || mm_tagpath=$mm_doxytagfile
+  ])
+])[]dnl
+  AC_MSG_RESULT([$mm_tagpath $mm_htmlrefdir])
+
+  AS_IF([test "x$USE_MAINTAINER_MODE" != xno && test ! -f "$mm_tagpath"],
+        [AC_MSG_WARN([Doxygen tag file $2 not found])])
+  AS_IF([test "x$mm_htmlrefdir" = x],
+        [AC_MSG_WARN([Location of external $1 documentation not set])])[]dnl
+
+  test "x$DOXYGEN_TAGFILES" = x || DOXYGEN_TAGFILES="$DOXYGEN_TAGFILES "
+  DOXYGEN_TAGFILES=$DOXYGEN_TAGFILES[\]"$mm_tagpath=$[mm_htmlref]m4_ifval([$3], [pub], [dir])[\]"
+  test "x$DOCINSTALL_FLAGS" = x || DOCINSTALL_FLAGS="$DOCINSTALL_FLAGS "
+  DOCINSTALL_FLAGS="[$]{DOCINSTALL_FLAGS}-l '$mm_tagname $mm_htmlrefdir'"dnl
+])
+
+## MM_ARG_WITH_TAGFILE_DOC(tagfilename, [module])
+##
+## Provide a --with-<tagfilebase>-doc=[/path/tagfile ]htmlrefdir configure
+## option, which may be used to specify the location of a tag file and the
+## path to the corresponding HTML reference documentation.  If the project
+## provides the maintainer mode option and maintainer mode is not enabled,
+## the user does not have to provide the full path to the tag file.  The
+## full path is only required for rebuilding the documentation.
+##
+## If the optional <module> argument has been specified, and either the tag
+## file or the HTML location have not been overridden by the user already,
+## try to retrieve the missing paths automatically via pkg-config.  Also ask
+## pkg-config for the URI to the online documentation, for use as the preset
+## location when the documentation is generated.
+##
+## A warning message will be shown if the HTML path could not be determined.
+## If maintainer mode is active, a warning is also displayed if the tag file
+## could not be found.
+##
+## The results are appended to the substitution variables DOXYGEN_TAGFILES
+## and DOCINSTALL_FLAGS, using the following format:
+##
+##  DOXYGEN_TAGFILES = "/path/tagfile=htmlrefpub" [...]
+##  DOCINSTALL_FLAGS = -l 'tagfile htmlrefdir' [...]
+##
+## The substitutions are intended to be used for the Doxygen configuration,
+## and as argument list to the doc-install.pl or installdox utility.
+##
+AC_DEFUN([MM_ARG_WITH_TAGFILE_DOC],
+[dnl
+m4_assert([$# >= 1])[]dnl
+m4_ifval([$2], [AC_REQUIRE([PKG_PROG_PKG_CONFIG])])[]dnl
+AC_REQUIRE([MM_ARG_ENABLE_DOCUMENTATION])[]dnl
+dnl
+AS_IF([test "x$ENABLE_DOCUMENTATION" != xno], [_MM_ARG_WITH_TAGFILE_DOC(
+  m4_quote(m4_bpatsubst([$1], [\([-+][0123456789]\|[+]*[._]\).*$])), [$1], [$2])])[]dnl
+])