## Copyright (c) 2009  Daniel Elstner <daniel.kitta@gmail.com>
##
## This file is part of mm-common.
##
## mm-common 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.
##
## mm-common 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 mm-common.  If not, see <http://www.gnu.org/licenses/>.

## Parameters:  book_name
## Overrides:   pubdocbase, htmlrefpub, book_title, htmlref_patterns,
##              doc_postprocess, doc_install, tagfile_to_devhelp2
## Files:       doc_input
## Output:      dist_noinst_DATA, DISTCLEANFILES, MAINTAINERCLEANFILES

# The base URL where the online documentation for C++ binding modules
# is located, including the trailing slash.
pubdocbase ?= http://www.gtkmm.org/docs/

# The URL of the module's online HTML reference documentation,
# excluding the trailing slash.
htmlrefpub ?= $(pubdocbase)$(book_name)/reference/html

# The title of the generated Devhelp book.
book_title ?= $(PACKAGE_NAME) Reference Manual

# A list of wildcard patterns matching the files from the HTML directory
# generated by Doxygen which should be distributed and installed.
htmlref_patterns ?=		\
	reference/html/*.html	\
	reference/html/*.css	\
	reference/html/*.png	\
	reference/html/*.gif

# Locations of utilities shipped with glibmm.  Made overridable
# in case the installed utilities cannot be used for some reason.
doc_postprocess     ?= $(PERL) -- "$(MMDOCTOOLDIR)/doc-postprocess.pl"
doc_install         ?= $(PERL) -- "$(MMDOCTOOLDIR)/doc-install.pl"
tagfile_to_devhelp2 ?= "$(MMDOCTOOLDIR)/tagfile-to-devhelp2.xsl"

# Names of the main output files.
doxytagfile = reference/$(book_name).tag
devhelpfile = reference/$(book_name).devhelp2

# Function: $(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)))

# Installation directories.
libdocdir    = $(datarootdir)/doc/$(book_name)
referencedir = $(libdocdir)/reference
htmlrefdir   = $(referencedir)/html
devhelpdir   = $(datadir)/devhelp/books/$(book_name)

dist_reference_DATA = $(doxytagfile)
dist_devhelp_DATA   = $(devhelpfile)
dist_noinst_DATA    = $(call vpath_listall,$(htmlref_patterns))

DISTCLEANFILES       = reference/doxygen.log
MAINTAINERCLEANFILES = $(doxytagfile) $(devhelpfile) reference/html/*

# The generic bit of the doc-install.pl command line.
doc_install_cmd = $(doc_install) --verbose --mode=0644

# The command and options used to install the files from the HTML reference
# documentation.  The $(subst) magic translates external tag references from
# absolute to relative paths if the destination is on the local file system
# and installed under the same prefix as the package being built.
htmlref_install = $(doc_install_cmd) $(subst @$(datarootdir)/doc/,@../../../,$(DOCINSTALL_FLAGS))

# Override the file installation program for dist_devhelp_DATA files.
# Note that this is not a documented feature as far as I'm aware, but
# Automake recognizes the override and does not try to assign its own
# default value.
dist_devhelpDATA_INSTALL = $(doc_install_cmd) --book-base='$(htmlrefdir)' -T --

# Helper variables to replicate each pattern with a $(srcdir)/ prefix.
# Also add quoting to prevent the shell from expanding the patterns.
htmlref_patterns_dup   = $(foreach file,$(htmlref_patterns),'$(file)' '$(srcdir)/$(file)')
htmlref_patterns_vpath = $(if $(srcdir:.=),$(htmlref_patterns_dup),$(htmlref_patterns:%='%'))

# Expand to a list of -name 'PATTERN' arguments for use with 'find'.
htmlref_find_patterns  = $(patsubst %,-name '%' -o,$(notdir $(htmlref_patterns))) -false

# The parameters to the Doxygen-to-Devhelp XSLT script
dh_xsl_params =	--stringparam book_title '$(book_title)' \
		--stringparam book_name '$(book_name)' \
		--stringparam book_base '$(htmlrefpub)'

# Regenerate the documentation automatically only in maintainer mode.
if MAINTAINER_MODE
doc_dependencies = $(doc_input) $(srcdir)/reference/Doxyfile.in
else
doc_dependencies =
endif

# Install the HTML reference documentation files with just one invocation
# of doc-install.pl to speed up the build process.  Make use of the --glob
# option, which tells it to perform filename globbing itself, like 'find'.
# This helps to avoid excessively long command lines, as some platforms
# have rather restrictive limits.
install-data-local: reference/html/index.html
	@$(NORMAL_INSTALL)
	$(MKDIR_P) '$(DESTDIR)$(htmlrefdir)'
	$(htmlref_install) -t '$(DESTDIR)$(htmlrefdir)' --glob -- $(htmlref_patterns_vpath)

# Delete files from the html installation directory.  Avoid recursive
# directory removal, and apply the same wildcard pattern as was used to
# select files for installation.
uninstall-local:
	@$(NORMAL_UNINSTALL)
	(cd '$(DESTDIR)$(htmlrefdir)' 2>/dev/null || exit 0; \
	 find . -type f \( $(htmlref_find_patterns) \) -exec rm -f '{}' '+')
	-test ! -r '$(DESTDIR)$(htmlrefdir)' || rmdir '$(DESTDIR)$(htmlrefdir)'

# Regenerate the Doxygen configuration file automatically.
reference/Doxyfile: $(srcdir)/reference/Doxyfile.in $(top_builddir)/config.status
	cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@

# Make sure that the documentation will always have been generated before
# executing the commands of a rule that depends on files in reference/html/.
reference/html/%: | $(doxytagfile)

# Run Doxygen to build the reference documentation. The generated tag file
# also functions as time stamp target for the documentation as a whole.
$(doxytagfile): $(doc_dependencies) | reference/Doxyfile
	-rm -f '$@'
	-rm -fr reference/html
	(echo '@INCLUDE =' reference/Doxyfile && echo 'INPUT =' $(doc_input)) | $(DOXYGEN) -
	$(doc_postprocess) 'reference/html/*.html'

# Run XSL transformation to generate a Devhelp book from a Doxygen tag file.
%.devhelp2: %.tag
	$(XSLTPROC) $(dh_xsl_params) -o $@ $(tagfile_to_devhelp2) $<

# Instruct GNU make to delete the targets of a rule after it failed, in
# order to avoid the complication of handling that situation manually.
.DELETE_ON_ERROR:
