From 5e1ccaeb603fb9f9b2b11cad13bbcf8682b33504 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Thu, 3 Sep 2009 13:04:59 +0100 Subject: [PATCH] docs: Clean up the additional documentation build MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit • 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 | 9 +-- configure.ac | 41 +++++------ doc/Makefile.am | 8 ++- doc/common/Makefile.am | 9 +++ doc/{cookbook => common}/common.xsl | 0 doc/{cookbook => common}/devhelp.xsl | 0 doc/{cookbook => common}/html.xsl | 0 doc/{cookbook => common}/ref-html-style.xsl | 0 doc/{cookbook => common}/style.css | 0 doc/cookbook/Makefile.am | 30 ++++---- ...lutter-cookbook.xml => clutter-cookbook.xml.in} | 7 +- doc/cookbook/cookbook.xsl | 14 ---- doc/manual/Makefile.am | 84 ++++++++++++---------- doc/manual/clutter-manual.xml.in | 9 ++- 14 files changed, 112 insertions(+), 99 deletions(-) create mode 100644 doc/common/Makefile.am rename doc/{cookbook => common}/common.xsl (100%) rename doc/{cookbook => common}/devhelp.xsl (100%) rename doc/{cookbook => common}/html.xsl (100%) rename doc/{cookbook => common}/ref-html-style.xsl (100%) rename doc/{cookbook => common}/style.css (100%) rename doc/cookbook/{clutter-cookbook.xml => clutter-cookbook.xml.in} (98%) delete mode 100644 doc/cookbook/cookbook.xsl diff --git a/.gitignore b/.gitignore index 6e62aee..70aa830 100644 --- 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 --- 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 --- 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 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 --- 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 --- a/doc/cookbook/clutter-cookbook.xml +++ b/doc/cookbook/clutter-cookbook.xml.in @@ -4,7 +4,7 @@ - + ]> @@ -17,7 +17,7 @@ - 2008 + 2009 Intel Corporation @@ -29,7 +29,8 @@ source code of this program. - The Clutter Cookbook &version; + The Clutter Cookbook + for Clutter &apiversion; diff --git a/doc/cookbook/cookbook.xsl b/doc/cookbook/cookbook.xsl deleted file mode 100644 index ef53df6..0000000 --- a/doc/cookbook/cookbook.xsl +++ /dev/null @@ -1,14 +0,0 @@ - - - - - - - - - - - diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am index f69bc5a..37b097e 100644 --- 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 --- a/doc/manual/clutter-manual.xml.in +++ b/doc/manual/clutter-manual.xml.in @@ -1,8 +1,8 @@ - + + ]> @@ -24,9 +24,8 @@ program. - - Clutter Application Developer Manual &appversion; - + Clutter Application Developer Manual + for Clutter &apiversion; -- 2.7.4