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

diff --git a/.gitignore b/.gitignore
index 6e62aee..70aa830 100644 (file)
--- a/.gitignore
+++ b/.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

diff --git a/configure.ac b/configure.ac
index 3873c25..db026d4 100644 (file)
--- a/configure.ac
+++ b/configure.ac
@@ -751,32 +751,32 @@ AC_SUBST(PANGO_PREFIX)
 
 dnl === Manual ================================================================
 
-AC_ARG_ENABLE([manual],
-              [AC_HELP_STRING([--enable-manual=@<:@no/yes@:>@],
-                              [Build application developers manual. Requires jw and xmlto.])],
-              [enable_manual=$enableval],
-              [enable_manual=no])
-
-AS_IF([test "x$enable_manual" = "xyes"],
+AC_ARG_ENABLE([docs],
+              [AC_HELP_STRING([--enable-docs=@<:@no/yes@:>@],
+                              [Build optional documentation; requires xsltproc and jw.])],
+              [enable_docs=$enableval],
+              [enable_docs=no])
+
+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_PATH_PROG(XMLTO, [xmlto], [no])
-        AS_IF([test "x$XMLTO" = "xno"],
-              [AC_MSG_ERROR(['xmlto' program needed by the manual not found in PATH])]
-        )
+              [
+                AC_MSG_WARN([jw not found; pdf generation has been disabled])
+              ],
+              [enable_pdfs=yes])
 
         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:"

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 78cea4d..7f32061 100644 (file)
--- a/doc/Makefile.am
+++ b/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

diff --git a/doc/common/Makefile.am b/doc/common/Makefile.am
new file mode 100644 (file)
index 0000000..c7511bd
--- /dev/null
+++ b/doc/common/Makefile.am
@@ -0,0 +1,9 @@
+NULL =
+
+EXTRA_DIST = \
+       common.xsl              \
+       devhelp.xsl             \
+       html.xsl                \
+       ref-html-style.xsl      \
+       style.css               \
+       $(NULL)

diff --git a/doc/cookbook/common.xsl b/doc/common/common.xsl
similarity index 100%
rename from doc/cookbook/common.xsl
rename to doc/common/common.xsl

diff --git a/doc/cookbook/devhelp.xsl b/doc/common/devhelp.xsl
similarity index 100%
rename from doc/cookbook/devhelp.xsl
rename to doc/common/devhelp.xsl

diff --git a/doc/cookbook/html.xsl b/doc/common/html.xsl
similarity index 100%
rename from doc/cookbook/html.xsl
rename to doc/common/html.xsl

diff --git a/doc/cookbook/ref-html-style.xsl b/doc/common/ref-html-style.xsl
similarity index 100%
rename from doc/cookbook/ref-html-style.xsl
rename to doc/common/ref-html-style.xsl

diff --git a/doc/cookbook/style.css b/doc/common/style.css
similarity index 100%
rename from doc/cookbook/style.css
rename to doc/common/style.css

diff --git a/doc/cookbook/Makefile.am b/doc/cookbook/Makefile.am
index f6203da..4a1c135 100644 (file)
--- a/doc/cookbook/Makefile.am
+++ b/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 =                   \
-        version.xml.in                 \
-       cookbook.xsl            \
-       common.xsl              \
-       devhelp.xsl             \
-       html.xsl                \
-       ref-html-style.xsl      \
-       style.css               \
-       $(IMAGE_FILES)
+EXTRA_DIST = $(IMAGE_FILES) clutter-cookbook.xml.in
 
 CLEANFILES = \
        pdf-build.stamp \
-       txt-build.stamp \
-       htmldoc-build.stamp
+       html-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
-all-local: html-build.stamp
+if ENABLE_PDFS
+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 -f *.pdf
+       @rm -rf html ; \
+       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

diff --git a/doc/cookbook/clutter-cookbook.xml b/doc/cookbook/clutter-cookbook.xml.in
similarity index 98%
rename from doc/cookbook/clutter-cookbook.xml
rename to doc/cookbook/clutter-cookbook.xml.in
index 360c94d..36b2b28 100644 (file)
--- a/doc/cookbook/clutter-cookbook.xml
+++ b/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"> <!-- {{{ -->

diff --git a/doc/cookbook/cookbook.xsl b/doc/cookbook/cookbook.xsl
deleted file mode 100644 (file)
index ef53df6..0000000
--- a/doc/cookbook/cookbook.xsl
+++ /dev/null
@@ -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>
-

diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am
index f69bc5a..37b097e 100644 (file)
--- a/doc/manual/Makefile.am
+++ b/doc/manual/Makefile.am
@@ -1,64 +1,76 @@
-DOCDIR = $(DESTDIR)/$(datadir)/doc/@PACKAGE@-@CLUTTER_API_VERSION@
-HTML_FILES =  html/*.html
-IMAGE_FILES = images/*.png
-EXTRA_DIST =  clutter-manual.xml.in manual.xsl style.css $(srcdir)/$(IMAGE_FILES)
-CLEANFILES = pdf-build.stamp txt-build.stamp htmldoc-build.stamp clutter-manual.xml
+HTML_DIR = $(datadir)/gtk-doc/html
+TARGET_DIR = $(HTML_DIR)/clutter-manual
+
+HTML_FILES = $(srcdir)/html/*.html
+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 && \
-       mv $(srcdir)/clutter-manual.pdf clutter-manual-@CLUTTER_API_VERSION@.pdf && \
-       touch pdf-build.stamp
-
-txt-build.stamp: clutter-manual.xml
-       $(XMLTO) txt $(srcdir)/clutter-manual.xml && \
-       mv $(srcdir)/clutter-manual.txt clutter-manual-@CLUTTER_API_VERSION@.txt && \
-       touch txt-build.stamp
+       $(JW) -b pdf $(srcdir)/clutter-manual.xml \
+       && mv -f $(srcdir)/clutter-manual.pdf clutter-manual-@CLUTTER_API_VERSION@.pdf \
+       && echo timestamp > $(@F)
 
-htmldoc-build.stamp: clutter-manual.xml
-       $(mkinstalldirs) html && \
-       $(XMLTO) -m manual.xsl -o html/ xhtml $(srcdir)/clutter-manual.xml && \
-       cp $(srcdir)/style.css html/ && \
-       touch htmldoc-build.stamp
+html-build.stamp: clutter-manual.xml
+       $(mkinstalldirs) html \
+       && $(XSLTPROC) --nonet --xinclude -o $(srcdir)/html/ \
+               --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)
 
-doc: txt-build.stamp htmldoc-build.stamp pdf-build.stamp
+if ENABLE_PDFS
+pdf_target = pdf-build.stamp
+else
+pdf_target =
+endif
 
-if ENABLE_MANUAL
-all-local: doc
+if ENABLE_DOCS
+all-local: html-build.stamp $(pdf_target)
 else
 all-local:
 endif
 
 clean-local:
-       rm -rf html/*.html
-       rm -f html/style.css
-       rm -f clutter-manual-*.txt
-       rm -f *.pdf
+       @rm -rf html ; \
+       rm -f *.pdf ; \
+       rm -f *.stamp
 
 uninstall-local:
-       rm -rf $(DOCDIR);
 
 install-data-local:
        installfiles=`echo $(srcdir)/html/*`; \
-       if test "$$installfiles" = '$(srcdir)/html/*'; then \
-       echo '-- Nothing to install' ; \
+       if test "$$installfiles" = '$(srcdir)/html/*'; \
+       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; \
-         $(INSTALL_DATA) $(srcdir)/clutter-manual-@CLUTTER_API_VERSION@.txt $(DOCDIR)/clutter-manual-@CLUTTER_API_VERSION@.txt; \
-         $(INSTALL_DATA) $(srcdir)/clutter-manual-@CLUTTER_API_VERSION@.pdf $(DOCDIR)/clutter-manual-@CLUTTER_API_VERSION@.pdf; \
-       fi
+       fi; \
+       $(INSTALL_DATA) $(top_srcdir)/doc/common/style.css $(DESTDIR)$(TARGET_DIR)/style.css; \
+       $(INSTALL_DATA) $(srcdir)/html/clutter-manual.devhelp   $(DESTDIR)$(TARGET_DIR)/clutter-manual.devhelp
 
 .PHONY : doc

diff --git a/doc/manual/clutter-manual.xml.in b/doc/manual/clutter-manual.xml.in
index 800ad9a..3e38d36 100644 (file)
--- a/doc/manual/clutter-manual.xml.in
+++ b/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 appurl "http://clutter-project.org">
+<!ENTITY apiversion "@CLUTTER_API_VERSION@">
+<!ENTITY appurl "http://www.clutter-project.org/docs">
 <!ENTITY author_mail "mallum@o-hand.com">
 ]>
 
@@ -24,9 +24,8 @@
                                program.
                        </para>
                </legalnotice>
-               <title>
-                       Clutter Application Developer Manual &appversion;
-               </title>
+               <title>Clutter Application Developer Manual</title>
+                <releaseinfo>for Clutter &apiversion;</releaseinfo>
        </bookinfo>
 
        <chapter id="intro">