GNOME.org
 

[librsvgmm] Integrate new external doc features with build

commit 39437cadc3d1c084bca9f941adcc998f9168cb62
Author: Daniel Elstner <danielk openismus com>
Date:   Mon Aug 3 00:38:10 2009 +0200

    Integrate new external doc features with build
    
    * configure.ac: Add calls to MM_ARG_WITH_TAGFILE_DOC() to locate the
    the Doxygen tag files of libstdc++, libsigc++, glibmm and cairomm.
    In principle, automatic configuration of the necessary parameters
    should work already.  However, it is pretty useless in practice for
    now, as no other modules integrate with the brand-new documentation
    magic yet.
    * build/doc-reference.am: Integrate with MM_ARG_WITH_TAGFILE_DOC()
    and the doc-install.pl script.  Implement translation of references
    to external documentation at install time.  Refactor and generalize
    the handling of VPATH searches.  Define customizable variables for
    referencing the module's public online documentation.
    * doc/Makefile.am (doc_install): Override doc-install.pl location
    to use the uninstalled script in the source tree.
    * doc/reference/Doxyfile.in (TAGFILES): Substitute @DOXYGEN_TAGFILES@
    list generated by MM_ARG_WITH_TAGFILE_DOC() during configure.
    (GENERATE_TAGFILE): Substitute @LIBRSVGMM_MODULE_NAME@ as the module
    name component of the tag file name.
    * doc/reference/doxytag_to_devhelp2.xsl: Add license information.
    (book_base): Rename parameter from reference_prefix.
    (keyword): Do not match @kind='variable' in xsl:template.

 build/doc-reference.am                |   85 +++++++++++++++++++++-----------
 configure.ac                          |    4 ++
 doc/Makefile.am                       |    4 +-
 doc/reference/Doxyfile.in             |    4 +-
 doc/reference/doxytag_to_devhelp2.xsl |   27 ++++++++--
 5 files changed, 86 insertions(+), 38 deletions(-)
---
diff --git a/build/doc-reference.am b/build/doc-reference.am
index 32e42cc..dc9fb65 100644
--- a/build/doc-reference.am
+++ b/build/doc-reference.am
@@ -15,32 +15,59 @@
 ## You should have received a copy of the GNU General Public License
 ## along with mm-autofu.  If not, see <http://www.gnu.org/licenses/>.
 
+pubdocbase ?= http://www.gtkmm.org/docs/
+htmlrefpub ?= $(pubdocbase)$(book_name)/reference/html
 book_title ?= $(PACKAGE_NAME) Reference Manual
 
-doxytagfile = reference/$(book_name).tag
-devhelpfile = reference/$(book_name).devhelp2
-
 htmlref_patterns ?=		\
 	reference/html/*.html	\
 	reference/html/*.css	\
 	reference/html/*.png	\
 	reference/html/*.gif
 
-htmlref_files = $(or $(wildcard\
-	$(htmlref_patterns)),$(wildcard\
-	$(addprefix $(srcdir)/,$(htmlref_patterns))))
+doxytagfile = reference/$(book_name).tag
+devhelpfile = reference/$(book_name).devhelp2
+
+# $(call vpath_listall,PATTERN ...)
+# Get all filenames which match a PATTERN from the list.  Look for files
+# relative to either the current directory or $(srcdir).  Strip $(srcdir)/
+# again before returning and remove any duplicates.
+vpath_srclist = $(patsubst $(srcdir)/%,%,$(wildcard $(addprefix $(srcdir)/,$(1))))
+vpath_listall = $(sort $(wildcard $(1)) $(if $(srcdir:.=),$(vpath_srclist)))
+
+# $(call vpath_resolve,FILENAME ...)
+# For each FILENAME, test whether the file exists relative to the current
+# directory.  If the file exists, return the filename unchanged, otherwise
+# prepend $(srcdir)/ to the filename.
+vpath_srctest = $(foreach file,$(1),$(or $(wildcard $(file)),$(srcdir)/$(file)))
+vpath_resolve = $(if $(srcdir:.=),$(vpath_srctest),$(1))
+
+libdocdir    = $(datarootdir)/doc/$(book_name)
+referencedir = $(libdocdir)/reference
+htmlrefdir   = $(referencedir)/html
+devhelpdir   = $(datadir)/devhelp/books/$(book_name)
+htmlreffiles = $(call vpath_listall,$(htmlref_patterns))
 
-referencedir = $(datarootdir)/doc/$(book_name)/reference
 dist_reference_DATA = $(doxytagfile)
+dist_devhelp_DATA   = $(devhelpfile)
+dist_noinst_DATA    = $(htmlreffiles)
 
-htmlrefdir = $(referencedir)/html
-dist_htmlref_DATA = $(htmlref_files)
+DISTCLEANFILES       = reference/doxygen.log
+MAINTAINERCLEANFILES = $(doxytagfile) $(devhelpfile) reference/html/*
 
-devhelpdir = $(datadir)/devhelp/books/$(book_name)
-dist_devhelp_DATA = $(devhelpfile)
+beautify_docs       ?= $(GMMPROC_DIR)/beautify_docs.pl
+doc_install         ?= $(GMMPROC_DIR)/doc-install.pl
+doxytag_to_devhelp2 ?= $(GMMPROC_DIR)/doxytag_to_devhelp2.xsl
+
+doc_install_cmd = $(PERL) -- $(doc_install) --verbose --mode=0644
+htmlref_install = $(doc_install_cmd) $(subst @$(datarootdir)/doc/,@../../../,$(DOCINSTALL_FLAGS))
+
+# Override the file installation program for dist_devhelp_DATA
+dist_devhelpDATA_INSTALL = $(doc_install_cmd) --book-base='$(htmlrefdir)' -T --
 
-DISTCLEANFILES = reference/doxygen.log
-MAINTAINERCLEANFILES = $(doxytagfile) $(devhelpfile)
+dh_xsl_params =	--stringparam book_title '$(book_title)' \
+		--stringparam book_name '$(book_name)' \
+		--stringparam book_base '$(htmlrefpub)'
 
 if MAINTAINER_MODE
 doc_dependencies = reference/Doxyfile $(doc_input)
@@ -48,28 +75,28 @@ else
 doc_dependencies =
 endif
 
-beautify_docs ?= $(GMMPROC_DIR)/beautify_docs.pl
-doxytag_to_devhelp2 ?= $(GMMPROC_DIR)/doxytag_to_devhelp2.xsl
-
-dh_xsl_params =	--stringparam book_title '$(book_title)' \
-		--stringparam book_name '$(book_name)' \
-		--stringparam reference_prefix html
-
-.DELETE_ON_ERROR:
+install-data-local: reference/html/index.html
+	@$(NORMAL_INSTALL)
+	$(MKDIR_P) '$(DESTDIR)$(htmlrefdir)'
+	$(htmlref_install) -t '$(DESTDIR)$(htmlrefdir)' -- $(call vpath_resolve,$(htmlreffiles))
 
-maintainer-clean-local:
-	-rm -rf reference/html
+uninstall-local:
+	@$(NORMAL_UNINSTALL)
+	(cd '$(DESTDIR)$(htmlrefdir)' 2>/dev/null || exit 0; rm -f $(notdir $(htmlref_patterns)))
+	-test ! -r '$(DESTDIR)$(htmlrefdir)' || rmdir '$(DESTDIR)$(htmlrefdir)'
 
 reference/Doxyfile: $(srcdir)/reference/Doxyfile.in $(top_builddir)/config.status
-	cd "$(top_builddir)" && $(SHELL) ./config.status '$(subdir)/$@'
+	cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@
+
+reference/html/%: | $(doxytagfile)
 
 $(doxytagfile): $(doc_dependencies)
 	-rm -f '$@'
-	-rm -rf reference/html
+	-rm -f reference/html/*
 	(echo '@INCLUDE =' reference/Doxyfile && echo 'INPUT =' $(doc_input)) | $(DOXYGEN) -
-	$(PERL) "$(beautify_docs)" reference/html
-
-reference/html/%: $(doxytagfile)
+	$(PERL) -- "$(beautify_docs)" reference/html
 
 %.devhelp2: %.tag
-	$(XSLTPROC) $(dh_xsl_params) -o '$@' "$(doxytag_to_devhelp2)" '$<'
+	$(XSLTPROC) $(dh_xsl_params) -o $@ "$(doxytag_to_devhelp2)" $<
+
+.DELETE_ON_ERROR:
diff --git a/configure.ac b/configure.ac
index 0fb708b..a6aaa8c 100644
--- a/configure.ac
+++ b/configure.ac
@@ -45,6 +45,10 @@ MM_PKG_CONFIG_SUBST([GTHREAD_CFLAGS], [--cflags-only-other gthread-2.0])
 MM_PKG_CONFIG_SUBST([GMMPROC_DIR], [--variable=gmmprocdir glibmm-2.4])
 
 MM_ARG_ENABLE_DOCUMENTATION
+MM_ARG_WITH_TAGFILE_DOC([libstdc++.tag])
+MM_ARG_WITH_TAGFILE_DOC([libsigc_doxygen_tags], [sigc++-2.0])
+MM_ARG_WITH_TAGFILE_DOC([glibmm_doxygen_tags],  [glibmm-2.4])
+MM_ARG_WITH_TAGFILE_DOC([cairomm_doxygen_tags], [cairomm-1.0])
 
 AC_LANG([C++])
 DK_ARG_ENABLE_WARNINGS([LIBRSVGMM_WXXFLAGS],
diff --git a/doc/Makefile.am b/doc/Makefile.am
index a04d72a..609e846 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -21,7 +21,9 @@ include $(top_srcdir)/librsvg/librsvgmm/filelist.am
 book_name = $(LIBRSVGMM_MODULE_NAME)
 doc_input = $(addprefix $(top_srcdir)/librsvg/librsvgmm/,$(files_built_h))
 
-dist_noinst_DATA = reference/doxytag_to_devhelp2.xsl
+doc_install = $(top_srcdir)/build/doc-install.pl
 doxytag_to_devhelp2 = $(srcdir)/reference/doxytag_to_devhelp2.xsl
 
 include $(top_srcdir)/build/doc-reference.am
+
+dist_noinst_DATA += reference/doxytag_to_devhelp2.xsl
diff --git a/doc/reference/Doxyfile.in b/doc/reference/Doxyfile.in
index 3f9149b..d2f96eb 100644
--- a/doc/reference/Doxyfile.in
+++ b/doc/reference/Doxyfile.in
@@ -241,8 +241,8 @@ SKIP_FUNCTION_MACROS   = YES
 #---------------------------------------------------------------------------
 # Configuration::additions related to external references
 #---------------------------------------------------------------------------
-TAGFILES               = $(DOXYGEN_TAGFILES)
-GENERATE_TAGFILE       = reference/librsvgmm-2.0.tag
+TAGFILES               = @DOXYGEN_TAGFILES@
+GENERATE_TAGFILE       = "reference/@LIBRSVGMM_MODULE_NAME  tag"
 ALLEXTERNALS           = NO
 EXTERNAL_GROUPS        = NO
 PERL_PATH              = @PERL@
diff --git a/doc/reference/doxytag_to_devhelp2.xsl b/doc/reference/doxytag_to_devhelp2.xsl
index 5c51b52..8dd55ec 100644
--- a/doc/reference/doxytag_to_devhelp2.xsl
+++ b/doc/reference/doxytag_to_devhelp2.xsl
@@ -1,17 +1,32 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <xsl:stylesheet version="1.0" xmlns="http://www.devhelp.net/book";
                 xmlns:xsl="http://www.w3.org/1999/XSL/Transform";>
+  <!--
+  Copyright (c) 2009  Daniel Elstner <daniel kitta gmail com>
 
+  XSL transformation from a Doxygen tag file to DevHelp 2 format.
+
+  This script is free software: you can redistribute it and/or modify
+  it under the terms of the GNU General Public License as published
+  by the Free Software Foundation, either version 2 of the License,
+  or (at your option) any later version.
+
+  This script is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with this script.  If not, see <http://www.gnu.org/licenses/>.
+  -->
   <xsl:output method="xml" version="1.0" indent="yes" encoding="UTF-8"/>
 
-  <!-- these are parameters so that this stylesheet can be used by multiple
-  libraries.  Pass them in on the commandline -->
   <xsl:param name="book_title"/>
   <xsl:param name="book_name"/>
-  <xsl:param name="reference_prefix"/>
+  <xsl:param name="book_base"/>
 
   <xsl:template match="/">
-    <book title="{$book_title}" name="{$book_name}" base="{$reference_prefix}"
+    <book title="{$book_title}" name="{$book_name}" base="{$book_base}"
           link="index.html" version="2" language="c++">
       <chapters>
         <sub name="Classes" link="classes.html">
@@ -40,7 +55,7 @@
   <xsl:template match="compound[ kind='class' or @kind='struct']" mode="keyword">
     <keyword type="struct" name="{name}" link="{filename}"/>
   </xsl:template>
-  <xsl:template match="member[ kind='function' or @kind='typedef' or @kind='variable']" mode="keyword">
+  <xsl:template match="member[ kind='function' or @kind='typedef']" mode="keyword">
     <keyword type="{ kind}" xsl:use-attribute-sets="keyword-member"/>
   </xsl:template>
   <xsl:template match="member[ kind='enumeration']" mode="keyword">
@@ -49,7 +64,7 @@
   <xsl:template match="member[ kind='enumvalue' or @kind='define']" mode="keyword">
     <keyword type="macro" xsl:use-attribute-sets="keyword-member"/>
   </xsl:template>
-
+  <!-- Ignore keywords of unknown type -->
   <xsl:template match="*" mode="keyword"/>
 
   <xsl:attribute-set name="keyword-member">
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]