docs: Clean up the additional documentation build

• Make the manual a DevHelp book

• Make the generation of PDFs of the cookbook and the manual optional

• Consequently, make the hard dependency on jw optional

• Clean up the checks and build for the additional documentation

.gitignore

@@ -31,13 +31,14 @@ clutter/stamp-*
 config.*
 configure
 depcomp
-/doc/cookbook/version.xml
-/doc/cookbook/version.xml
 /doc/cookbook/*.pdf
-/doc/cookbook/*.txt
 /doc/cookbook/html
 /doc/cookbook/*.stamp
-doc/manual/clutter-manual.xml
+/doc/cookbook/clutter-cookbook.xml
+/doc/manual/*.pdf
+/doc/manual/html
+/doc/manual/*.stamp
+/doc/manual/clutter-manual.xml
 doc/reference/clutter/clutter-*.txt
 !/doc/reference/clutter/clutter-sections.txt
 doc/reference/clutter/html

configure.ac

@@ -751,32 +751,32 @@ AC_SUBST(PANGO_PREFIX)
 
 dnl === Manual ================================================================
 
-AC_ARG_ENABLE([manual],
+AC_ARG_ENABLE([docs],
-              [AC_HELP_STRING([--enable-manual=@<:@no/yes@:>@],
+              [AC_HELP_STRING([--enable-docs=@<:@no/yes@:>@],
-                              [Build application developers manual. Requires jw and xmlto.])],
+                              [Build optional documentation; requires xsltproc and jw.])],
-              [enable_manual=$enableval],
+              [enable_docs=$enableval],
-              [enable_manual=no])
+              [enable_docs=no])
 
-AS_IF([test "x$enable_manual" = "xyes"],
+enable_pdfs=no
+AS_IF([test "x$enable_docs" = "xyes"],
       [
         AC_PATH_PROG(JW, [jw], [no])
         AS_IF([test "x$JW" = "xno"],
-              [AC_MSG_ERROR(['jw' program needed by the manual not found in PATH])]
+              [
-        )
+                AC_MSG_WARN([jw not found; pdf generation has been disabled])
-
+              ],
-        AC_PATH_PROG(XMLTO, [xmlto], [no])
+              [enable_pdfs=yes])
-        AS_IF([test "x$XMLTO" = "xno"],
-              [AC_MSG_ERROR(['xmlto' program needed by the manual not found in PATH])]
-        )
 
         AC_PATH_PROG(XSLTPROC, [xsltproc], [no])
         AS_IF([test "x$XSLTPROC" = "xno"],
-              [AC_MSG_ERROR(['xsltproc' needed by the manual not found in PATH])]
+              [
-        )
+                AC_MSG_ERROR([xsltproc not found])
+              ])
       ]
 )
 
-AM_CONDITIONAL(ENABLE_MANUAL, [test "x$enable_manual" = "xyes"])
+AM_CONDITIONAL(ENABLE_DOCS, [test "x$enable_docs" = "xyes"])
+AM_CONDITIONAL(ENABLE_PDFS, [test "x$enable_pdfs" = "xyes"])
 
 dnl === I18N ==================================================================
 
@@ -847,10 +847,11 @@ AC_CONFIG_FILES([
         doc/reference/clutter/clutter-docs.xml
         doc/reference/cogl/Makefile
         doc/reference/cogl/cogl-docs.xml
-        doc/manual/clutter-manual.xml
+        doc/common/Makefile
         doc/manual/Makefile
-        doc/cookbook/version.xml
+        doc/manual/clutter-manual.xml
         doc/cookbook/Makefile
+        doc/cookbook/clutter-cookbook.xml
         po/Makefile.in
         clutter.pc
 ])
@@ -877,7 +878,7 @@ echo "        Compiler flags: ${MAINTAINER_CFLAGS}"
 echo ""
 echo " • Documentation:"
 echo "        Build API Reference: ${enable_gtk_doc}"
-echo "        Build Manual: ${enable_manual}"
+echo "        Build Additional Documentation: ${enable_docs}"
 
 echo ""
 echo " • Extra:"

doc/Makefile.am

@@ -1 +1,7 @@
-SUBDIRS=reference manual
+SUBDIRS = reference
+
+if ENABLE_DOCS
+SUBDIRS += common cookbook manual
+endif
+
+DIST_SUBDIRS = reference common cookbook manual

doc/common/Makefile.am

@@ -0,0 +1,9 @@
+NULL =
+
+EXTRA_DIST = \
+	common.xsl		\
+	devhelp.xsl		\
+	html.xsl		\
+	ref-html-style.xsl	\
+	style.css		\
+	$(NULL)

doc/cookbook/Makefile.am

@@ -4,20 +4,11 @@ TARGET_DIR = $(HTML_DIR)/clutter-cookbook
 HTML_FILES = $(srcdir)/html/*.html
 IMAGE_FILES = $(srcdir)/images/*.png
 
-EXTRA_DIST =  			\
+EXTRA_DIST = $(IMAGE_FILES) clutter-cookbook.xml.in
-        version.xml.in 		\
-	cookbook.xsl 		\
-	common.xsl		\
-	devhelp.xsl		\
-	html.xsl		\
-	ref-html-style.xsl	\
-	style.css 		\
-	$(IMAGE_FILES)
 
 CLEANFILES = \
 	pdf-build.stamp \
-	txt-build.stamp \
+	html-build.stamp
-	htmldoc-build.stamp
 
 pdf-build.stamp: clutter-cookbook.xml
 	SP_ENCODING=XML SP_CHARSET_FIXED=YES \
@@ -28,6 +19,7 @@ pdf-build.stamp: clutter-cookbook.xml
 html-build.stamp: clutter-cookbook.xml
 	$(mkinstalldirs) html \
 	&& $(XSLTPROC) --nonet --xinclude -o $(srcdir)/html/ \
+		--path $(top_srcdir)/doc/common \
 		--path $(srcdir) \
 		--stringparam gtkdoc.bookname "clutter-cookbook" \
 		--stringparam gtkdoc.version @CLUTTER_API_VERSION@ \
@@ -35,15 +27,21 @@ html-build.stamp: clutter-cookbook.xml
 	$(srcdir)/clutter-cookbook.xml \
 	&& echo timestamp > $(@F)
 
-if ENABLE_MANUAL
+if ENABLE_PDFS
-all-local: html-build.stamp
+pdf_target = pdf-build.stamp
+else
+pdf_target =
+endif
+
+if ENABLE_DOCS
+all-local: html-build.stamp $(pdf_target)
 else
 all-local:
 endif
 
 clean-local:
-	rm -rf html
+	@rm -rf html ; \
-	rm -f *.pdf
+	rm -f *.pdf ; \
 	rm -f *.stamp
 
 uninstall-local:
@@ -72,7 +70,7 @@ install-data-local:
 	    fi \
 	  done; \
 	fi; \
-	$(INSTALL_DATA) $(srcdir)/style.css $(DESTDIR)$(TARGET_DIR)/style.css; \
+	$(INSTALL_DATA) $(top_srcdir)/doc/common/style.css $(DESTDIR)$(TARGET_DIR)/style.css; \
 	$(INSTALL_DATA) $(srcdir)/html/clutter-cookbook.devhelp	$(DESTDIR)$(TARGET_DIR)/clutter-cookbook.devhelp
 
 .PHONY : doc

doc/cookbook/clutter-cookbook.xml.in

@@ -4,7 +4,7 @@
 <!ENTITY appurl "http://clutter-project.org">
 <!ENTITY docurl "http://clutter-project.org/docs/">
 <!ENTITY author_mail "ebassi@linux.intel.com">
-<!ENTITY version SYSTEM "version.xml">
+<!ENTITY apiversion "@CLUTTER_API_VERSION@">
 ]>
 
 <book lang="en">
@@ -17,7 +17,7 @@
     </author>
 
     <copyright>
-      <year>2008</year>
+      <year>2009</year>
       <holder>Intel Corporation</holder>
     </copyright>
 
@@ -29,7 +29,8 @@
       source code of this program.</para>
     </legalnotice>
 
-    <title>The Clutter Cookbook &version;</title>
+    <title>The Clutter Cookbook</title>
+    <releaseinfo>for Clutter &apiversion;</releaseinfo>
   </bookinfo> <!-- }}} -->
 
   <chapter id="introduction"> <!-- {{{ -->

doc/cookbook/cookbook.xsl

@@ -1,14 +0,0 @@
-<?xml version='1.0'?>
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-                version='1.0'
-                xmlns="http://www.w3.org/TR/xhtml1/transitional"
-                exclude-result-prefixes="#default">
-
-<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl"/>
-
-<!-- Use stylesheet -->
-<xsl:param name="html.stylesheet" select="'style.css'"/>
-<xsl:param name="chunker.output.encoding" select="'UTF-8'"/>
-
-</xsl:stylesheet>
-

doc/manual/Makefile.am

@@ -1,64 +1,76 @@
-DOCDIR = $(DESTDIR)/$(datadir)/doc/@PACKAGE@-@CLUTTER_API_VERSION@
+HTML_DIR = $(datadir)/gtk-doc/html
-HTML_FILES =  html/*.html
+TARGET_DIR = $(HTML_DIR)/clutter-manual
-IMAGE_FILES = images/*.png
+
-EXTRA_DIST =  clutter-manual.xml.in manual.xsl style.css $(srcdir)/$(IMAGE_FILES)
+HTML_FILES = $(srcdir)/html/*.html
-CLEANFILES = pdf-build.stamp txt-build.stamp htmldoc-build.stamp clutter-manual.xml
+IMAGE_FILES = $(srcdir)/images/*.png
+
+EXTRA_DIST = $(IMAGE_FILES)
+
+CLEANFILES = \
+	pdf-build.stamp \
+	html-build.stamp
 
 pdf-build.stamp: clutter-manual.xml
 	SP_ENCODING=XML SP_CHARSET_FIXED=YES \
-	$(JW) -b pdf $(srcdir)/clutter-manual.xml && \
+	$(JW) -b pdf $(srcdir)/clutter-manual.xml \
-	mv $(srcdir)/clutter-manual.pdf clutter-manual-@CLUTTER_API_VERSION@.pdf && \
+	&& mv -f $(srcdir)/clutter-manual.pdf clutter-manual-@CLUTTER_API_VERSION@.pdf \
-	touch pdf-build.stamp
+	&& echo timestamp > $(@F)
 
-txt-build.stamp: clutter-manual.xml
+html-build.stamp: clutter-manual.xml
-	$(XMLTO) txt $(srcdir)/clutter-manual.xml && \
+	$(mkinstalldirs) html \
-	mv $(srcdir)/clutter-manual.txt clutter-manual-@CLUTTER_API_VERSION@.txt && \
+	&& $(XSLTPROC) --nonet --xinclude -o $(srcdir)/html/ \
-	touch txt-build.stamp
+		--path $(top_srcdir)/doc/common \
+		--path $(srcdir) \
+		--stringparam gtkdoc.bookname "clutter-manual" \
+		--stringparam gtkdoc.version @CLUTTER_API_VERSION@ \
+		$(srcdir)/ref-html-style.xsl \
+	$(srcdir)/clutter-manual.xml \
+	&& echo timestamp > $(@F)
 
-htmldoc-build.stamp: clutter-manual.xml
+if ENABLE_PDFS
-	$(mkinstalldirs) html && \
+pdf_target = pdf-build.stamp
-	$(XMLTO) -m manual.xsl -o html/ xhtml $(srcdir)/clutter-manual.xml && \
+else
-	cp $(srcdir)/style.css html/ && \
+pdf_target =
-	touch htmldoc-build.stamp
+endif
 
-doc: txt-build.stamp htmldoc-build.stamp pdf-build.stamp
+if ENABLE_DOCS
-
+all-local: html-build.stamp $(pdf_target)
-if ENABLE_MANUAL
-all-local: doc
 else
 all-local:
 endif
 
 clean-local:
-	rm -rf html/*.html
+	@rm -rf html ; \
-	rm -f html/style.css
+	rm -f *.pdf ; \
-	rm -f clutter-manual-*.txt
+	rm -f *.stamp
-	rm -f *.pdf
 
 uninstall-local:
-	rm -rf $(DOCDIR);
 
 install-data-local:
 	installfiles=`echo $(srcdir)/html/*`; \
-	if test "$$installfiles" = '$(srcdir)/html/*'; then \
+	if test "$$installfiles" = '$(srcdir)/html/*'; \
-	echo '-- Nothing to install' ; \
+	then echo '-- Nothing to install' ; \
 	else \
-	  $(mkinstalldirs) $(DOCDIR)/html/images ; \
+	  $(mkinstalldirs) $(DESTDIR)$(TARGET_DIR) ; \
 	  for file in `ls $(srcdir)/$(HTML_FILES)`; do \
 	    if [ -f $$file ]; then \
 	      basefile=`echo $$file | sed -e 's,^.*/,,'`; \
-	      $(INSTALL_DATA) $$file $(DOCDIR)/html/$$basefile; \
+	      $(INSTALL_DATA) $$file $(DESTDIR)$(TARGET_DIR)/$$basefile; \
 	    fi \
 	  done; \
+	fi; \
+	if [ -d $(srcdir)/images ]; \
+	then \
+	  $(mkinstalldirs) $(DESTDIR)$(TARGET_DIR)/images ; \
 	  for file in `ls $(srcdir)/$(IMAGE_FILES)`; do \
-	    if [ -f $$file ]; then \
+	    if [ -f $$file ]; \
+	    then \
 	      basefile=`echo $$file | sed -e 's,^.*/,,'`; \
-	      $(INSTALL_DATA) $$file $(DOCDIR)/html/images/$$basefile; \
+	      $(INSTALL_DATA) $$file $(DESTDIR)$(TARGET_DIR)/images/$$basefile; \
 	    fi \
 	  done; \
-	  $(INSTALL_DATA) $(srcdir)/style.css $(DOCDIR)/html/style.css; \
+	fi; \
-	  $(INSTALL_DATA) $(srcdir)/clutter-manual-@CLUTTER_API_VERSION@.txt $(DOCDIR)/clutter-manual-@CLUTTER_API_VERSION@.txt; \
+	$(INSTALL_DATA) $(top_srcdir)/doc/common/style.css $(DESTDIR)$(TARGET_DIR)/style.css; \
-	  $(INSTALL_DATA) $(srcdir)/clutter-manual-@CLUTTER_API_VERSION@.pdf $(DOCDIR)/clutter-manual-@CLUTTER_API_VERSION@.pdf; \
+	$(INSTALL_DATA) $(srcdir)/html/clutter-manual.devhelp	$(DESTDIR)$(TARGET_DIR)/clutter-manual.devhelp
-	fi
 
 .PHONY : doc

doc/manual/clutter-manual.xml.in

@@ -1,8 +1,8 @@
 <?xml version='1.0' encoding='UTF-8'?>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY appversion "@CLUTTER_MAJORMINOR@">
+<!ENTITY apiversion "@CLUTTER_API_VERSION@">
-<!ENTITY appurl "http://clutter-project.org">
+<!ENTITY appurl "http://www.clutter-project.org/docs">
 <!ENTITY author_mail "mallum@o-hand.com">
 ]>
 
@@ -24,9 +24,8 @@
 				program.
 			</para>
 		</legalnotice>
-		<title>
+		<title>Clutter Application Developer Manual</title>
-			Clutter Application Developer Manual &appversion;
+                <releaseinfo>for Clutter &apiversion;</releaseinfo>
-		</title>
 	</bookinfo>
 
 	<chapter id="intro">