[librsvgmm] Document include file for the documentation build

[Daniel Elstner <daniel src gnome org>]

commit 7fb03a538d920108aa5712c3feff8bc48a7212e2
Author: Daniel Elstner <daniel kitta gmail com>
Date:   Mon Aug 3 20:57:49 2009 +0200

    Document include file for the documentation build
    
    * build/doc-reference.am: Document input variables and overridable
    parameters.  Add comments to document the purpose of each variable
    or rule defined.

 build/compile-binding.am |    2 +
 build/doc-reference.am   |   54 +++++++++++++++++++++++++++++++++++++++++----
 2 files changed, 51 insertions(+), 5 deletions(-)
---
diff --git a/build/compile-binding.am b/build/compile-binding.am
index 14297bb..8f6145e 100644
--- a/build/compile-binding.am
+++ b/build/compile-binding.am
@@ -38,4 +38,6 @@ binding_private_HEADERS	= $(files_built_ph)
 binding_built_sources	= $(files_built_cc) $(files_built_h) $(files_built_ph)
 MAINTAINERCLEANFILES	= $(addprefix $(srcdir)/,$(binding_built_sources))
 
+# 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:
diff --git a/build/doc-reference.am b/build/doc-reference.am
index dc9fb65..79df726 100644
--- a/build/doc-reference.am
+++ b/build/doc-reference.am
@@ -15,16 +15,38 @@
 ## You should have received a copy of the GNU General Public License
 ## along with mm-autofu.  If not, see <http://www.gnu.org/licenses/>.
 
+## Parameters:  book_name
+## Overrides:   pubdocbase, htmlrefpub, book_title, htmlref_patterns,
+##              beautify_docs, doc_install, doxytag_to_devhelp2
+## Files:       doc_input
+## Output:      dist_noinst_DATA
+
+# 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 gmmproc.  Made overridable
+# in case the installed utilities cannot be used for some reason.
+beautify_docs       ?= $(GMMPROC_DIR)/beautify_docs.pl
+doc_install         ?= $(GMMPROC_DIR)/doc-install.pl
+doxytag_to_devhelp2 ?= $(GMMPROC_DIR)/doxytag_to_devhelp2.xsl
+
+# Names of the main output files.
 doxytagfile = reference/$(book_name).tag
 devhelpfile = reference/$(book_name).devhelp2
 
@@ -42,10 +64,13 @@ vpath_listall = $(sort $(wildcard $(1)) $(if $(srcdir:.=),$(vpath_srclist)))
 vpath_srctest = $(foreach file,$(1),$(or $(wildcard $(file)),$(srcdir)/$(file)))
 vpath_resolve = $(if $(srcdir:.=),$(vpath_srctest),$(1))
 
+# Installation directories
 libdocdir    = $(datarootdir)/doc/$(book_name)
 referencedir = $(libdocdir)/reference
 htmlrefdir   = $(referencedir)/html
 devhelpdir   = $(datadir)/devhelp/books/$(book_name)
+
+# List of files in the HTML reference documentation
 htmlreffiles = $(call vpath_listall,$(htmlref_patterns))
 
 dist_reference_DATA = $(doxytagfile)
@@ -55,48 +80,67 @@ dist_noinst_DATA    = $(htmlreffiles)
 DISTCLEANFILES       = reference/doxygen.log
 MAINTAINERCLEANFILES = $(doxytagfile) $(devhelpfile) reference/html/*
 
-beautify_docs       ?= $(GMMPROC_DIR)/beautify_docs.pl
-doc_install         ?= $(GMMPROC_DIR)/doc-install.pl
-doxytag_to_devhelp2 ?= $(GMMPROC_DIR)/doxytag_to_devhelp2.xsl
-
+# The generic bit of the doc-install.pl command line
 doc_install_cmd = $(PERL) -- $(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
+# 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 appears to recognize the override and does not try to assign
+# its own default value.
 dist_devhelpDATA_INSTALL = $(doc_install_cmd) --book-base='$(htmlrefdir)' -T --
 
+# 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 = reference/Doxyfile $(doc_input)
 else
 doc_dependencies =
 endif
 
+# Install the HTML reference documentation files with just one invocation
+# of doc-install.pl to speed up the build process.
 install-data-local: reference/html/index.html
 	@$(NORMAL_INSTALL)
 	$(MKDIR_P) '$(DESTDIR)$(htmlrefdir)'
 	$(htmlref_install) -t '$(DESTDIR)$(htmlrefdir)' -- $(call vpath_resolve,$(htmlreffiles))
 
+# Delete all files in the html installation directory, but avoid recursion
+# in order to limit the harm in case something goes horribly wrong.
 uninstall-local:
 	@$(NORMAL_UNINSTALL)
 	(cd '$(DESTDIR)$(htmlrefdir)' 2>/dev/null || exit 0; rm -f $(notdir $(htmlref_patterns)))
 	-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)
 	-rm -f '$@'
 	-rm -f reference/html/*
 	(echo '@INCLUDE =' reference/Doxyfile && echo 'INPUT =' $(doc_input)) | $(DOXYGEN) -
 	$(PERL) -- "$(beautify_docs)" reference/html
 
+# Run XSL transformation to generate a Devhelp book from a Doxygen tag file.
 %.devhelp2: %.tag
 	$(XSLTPROC) $(dh_xsl_params) -o $@ "$(doxytag_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: