Add the Clutter Cookbook to the build

The "Clutter Cookbook" is a document designed to contain solutions
to common problems applications developers might encounter when using
Clutter. It is meant as a companion to the API reference but it
requires knowledge of the Clutter API and framework.

diff --git a/.gitignore b/.gitignore
index 962ebc1..ab2839a 100644 (file)
--- a/.gitignore
+++ b/.gitignore
@@ -31,6 +31,7 @@ clutter/stamp-*
 config.*
 configure
 depcomp
+/doc/cookbook/version.xml
 doc/manual/clutter-manual.xml
 doc/reference/clutter/clutter-*.txt
 !/doc/reference/clutter/clutter-sections.txt

diff --git a/configure.ac b/configure.ac
index 134d846..7c1e7a0 100644 (file)
--- a/configure.ac
+++ b/configure.ac
@@ -844,6 +844,8 @@ AC_CONFIG_FILES([
         doc/reference/cogl/cogl-docs.xml
         doc/manual/clutter-manual.xml
         doc/manual/Makefile
+        doc/cookbook/version.xml
+        doc/cookbook/Makefile
         po/Makefile.in
         clutter.pc
 ])

diff --git a/doc/cookbook/Makefile.am b/doc/cookbook/Makefile.am
new file mode 100644 (file)
index 0000000..d668819
--- /dev/null
+++ b/doc/cookbook/Makefile.am
@@ -0,0 +1,71 @@
+DOCDIR = $(DESTDIR)/$(datadir)/doc/@PACKAGE@-@CLUTTER_API_VERSION@/cookbook
+HTML_FILES =  html/*.html
+IMAGE_FILES = images/*.png
+EXTRA_DIST =  \
+        version.xml.in \
+       cookbook.xsl \
+       style.css \
+       $(srcdir)/$(IMAGE_FILES)
+CLEANFILES = \
+       pdf-build.stamp \
+       txt-build.stamp \
+       htmldoc-build.stamp
+
+pdf-build.stamp: clutter-cookbook.xml
+       SP_ENCODING=XML SP_CHARSET_FIXED=YES \
+       $(JW) -b pdf $(srcdir)/clutter-cookbook.xml && \
+       mv $(srcdir)/clutter-cookbook.pdf clutter-cookbook-@CLUTTER_API_VERSION@.pdf && \
+       touch pdf-build.stamp
+
+txt-build.stamp: clutter-cookbook.xml
+       $(XMLTO) txt $(srcdir)/clutter-cookbook.xml && \
+       mv $(srcdir)/clutter-cookbook.txt clutter-cookbook-@CLUTTER_MAJORMINOR@.txt && \
+       touch txt-build.stamp
+
+htmldoc-build.stamp: clutter-cookbook.xml
+       $(mkinstalldirs) html && \
+       $(XMLTO) -m cookbook.xsl -o html/ xhtml $(srcdir)/clutter-cookbook.xml && \
+       cp $(srcdir)/style.css html/ && \
+       touch htmldoc-build.stamp
+
+doc: txt-build.stamp htmldoc-build.stamp pdf-build.stamp
+
+if ENABLE_MANUAL
+all-local: doc
+else
+all-local:
+endif
+
+clean-local:
+       rm -rf html/*.html
+       rm -f html/style.css
+       rm -f clutter-cookbook-*.txt
+       rm -f *.pdf
+
+uninstall-local:
+       rm -rf $(DOCDIR);
+
+install-data-local:
+       installfiles=`echo $(srcdir)/html/*`; \
+       if test "$$installfiles" = '$(srcdir)/html/*'; then \
+       echo '-- Nothing to install' ; \
+       else \
+         $(mkinstalldirs) $(DOCDIR)/html/images ; \
+         for file in `ls $(srcdir)/$(HTML_FILES)`; do \
+           if [ -f $$file ]; then \
+             basefile=`echo $$file | sed -e 's,^.*/,,'`; \
+             $(INSTALL_DATA) $$file $(DOCDIR)/html/$$basefile; \
+           fi \
+         done; \
+         for file in `ls $(srcdir)/$(IMAGE_FILES)`; do \
+           if [ -f $$file ]; then \
+             basefile=`echo $$file | sed -e 's,^.*/,,'`; \
+             $(INSTALL_DATA) $$file $(DOCDIR)/html/images/$$basefile; \
+           fi \
+         done; \
+         $(INSTALL_DATA) $(srcdir)/style.css $(DOCDIR)/html/style.css; \
+         $(INSTALL_DATA) $(srcdir)/clutter-cookbook-@CLUTTER_MAJORMINOR@.txt $(DOCDIR)/clutter-cookbook-@CLUTTER_MAJORMINOR@.txt; \
+         $(INSTALL_DATA) $(srcdir)/clutter-cookbook-@CLUTTER_MAJORMINOR@.pdf $(DOCDIR)/clutter-cookbook-@CLUTTER_MAJORMINOR@.pdf; \
+       fi
+
+.PHONY : doc

diff --git a/doc/cookbook/clutter-cookbook.xml b/doc/cookbook/clutter-cookbook.xml
new file mode 100644 (file)
index 0000000..2df56e8
--- /dev/null
+++ b/doc/cookbook/clutter-cookbook.xml
@@ -0,0 +1,200 @@
+<?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 appurl "http://clutter-project.org">
+<!ENTITY docurl "http://clutter-project.org/docs/">
+<!ENTITY author_mail "ebassi@linux.intel.com">
+<!ENTITY version SYSTEM "version.xml">
+]>
+
+<book lang="en">
+  <bookinfo> <!-- {{{ -->
+    <author>
+      <firstname>Emmanuele</firstname>
+      <surname>Bassi</surname>
+      <address><email>&author_mail;</email></address>
+    </author>
+
+    <copyright>
+      <year>2008</year>
+      <holder>Intel Corporation</holder>
+    </copyright>
+
+    <legalnotice>
+      <para>This document is distributed 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. A copy
+      of this license can be found in the file COPYING included with the
+      source code of this program.</para>
+    </legalnotice>
+
+    <title>The Clutter Cookbook &version;</title>
+  </bookinfo> <!-- }}} -->
+
+  <chapter id="introduction"> <!-- {{{ -->
+    <title>Introduction</title>
+
+    <section>
+      <title>About Clutter</title>
+
+      <para>FIXME</para>
+    </section>
+
+    <section>
+      <title>About this document</title>
+
+      <para>This document tries to provide examples on how to perform some
+      common tasks when building an application or a toolkit using the
+      Clutter library.</para>
+
+      <para>This document is available in various formats like HTML,
+      text and PDF. The latest version is always available at
+      <ulink url="&docurl;">&docurl;</ulink>.</para>
+    </section>
+
+    <section>
+      <title>Where to get Clutter</title>
+
+      <para>You can obtain Clutter from <ulink url="&appurl;">&appurl;</ulink>
+      or perhaps from your distributor.</para>
+    </section>
+
+    <section>
+      <title>License</title>
+
+      <para>Clutter is distributed under the terms of the GNU Lesser General
+      Public License as published by the Free Software Foundation; either
+      version 2 of the License, or (at your option) any later version. A copy
+      of this license can be found in the file COPYING included with the
+      source code of this program.</para>
+    </section>
+
+  </chapter> <!-- introduction }}} -->
+
+  <chapter id="actors"> <!-- actors {{{ -->
+    <title>Actors</title>
+
+    <epigraph>
+      <attribution>the author of the epigraph</attribution>
+      <para>a short epigraph</para>
+    </epigraph>
+
+    <section id="actors-introduction">
+      <title>Introduction</title>
+
+      <para>introduction</para>
+    </section>
+
+    <section id="actors-recipe-1"> <!-- recipe 1 {{{ -->
+      <title>A problem involving actors</title>
+
+      <section>
+        <title>Problem</title>
+
+        <para>Description of the problem</para>
+      </section>
+
+      <section>
+        <title>Solution</title>
+
+        <para>The solution of the problem, with the source code</para>
+      </section>
+
+      <section>
+        <title>Discussion</title>
+
+        <para>Discussion of the solution, with eventual mentions of
+        possible alternatives</para>
+      </section>
+
+    </section> <!-- recipe 1 }}} -->
+
+  </chapter> <!-- actors }}} -->
+
+  <chapter id="textures"> <!-- textures {{{ -->
+    <title>Textures</title>
+
+    <epigraph>
+      <attribution>the author of the epigraph</attribution>
+      <para>a short epigraph</para>
+    </epigraph>
+
+    <section id="textures-introduction">
+      <title>Introduction</title>
+
+      <para>introduction</para>
+    </section>
+
+    <section> <!-- recipe 1 {{{ -->
+      <title>Maintaining the aspect ratio when loading a texture</title>
+
+      <section>
+        <title>Problem</title>
+
+        <para></para>
+      </section>
+
+      <section>
+        <title>Solution</title>
+
+        <para></para>
+      </section>
+
+      <section>
+        <title>Discussion</title>
+
+        <para></para>
+      </section>
+
+    </section> <!-- recipe 1 }}} -->
+
+  </chapter> <!-- textures }}} -->
+
+  <chapter id="animations"> <!-- animations {{{ -->
+    <title>Animations</title>
+
+    <epigraph>
+      <attribution>the author of the epigraph</attribution>
+      <para>a short epigraph</para>
+    </epigraph>
+
+    <section id="animations-introduction">
+      <title>Introduction</title>
+
+      <para>introduction</para>
+    </section>
+
+    <section> <!-- recipe 1 {{{ -->
+      <title>Inverting Animations</title>
+
+      <section>
+        <title>Problem</title>
+
+        <para></para>
+      </section>
+
+      <section>
+        <title>Solution</title>
+
+        <para></para>
+      </section>
+
+      <section>
+        <title>Discussion</title>
+
+        <para></para>
+      </section>
+
+    </section> <!-- recipe 1 }}} -->
+
+  </chapter> <!-- animations }}} -->
+
+  <appendix id="contributing"> <!-- {{{ -->
+    <title>Contributing to this document</title>
+
+    <para>This document is written in Docbook XML. The source file for this
+    document is located in the subdirectory "doc/cookbook" of the source
+    directory of Clutter.</para>
+  </appendix> <!-- contributing }}} -->
+
+</book>

diff --git a/doc/cookbook/cookbook.xsl b/doc/cookbook/cookbook.xsl
new file mode 100644 (file)
index 0000000..ef53df6
--- /dev/null
+++ b/doc/cookbook/cookbook.xsl
@@ -0,0 +1,14 @@
+<?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/cookbook/style.css b/doc/cookbook/style.css
new file mode 100644 (file)
index 0000000..c299fdd
--- /dev/null
+++ b/doc/cookbook/style.css
@@ -0,0 +1,97 @@
+body address
+{
+  line-height: 1.3;
+  margin: .6em 0;
+}
+
+body blockquote
+{
+  margin-top: .75em;
+  line-height: 1.5;
+  margin-bottom: .75em;
+}
+
+html body
+{
+  margin: 1em 2% 1em 2%;
+  line-height: 1.2;
+  background-color: #ffffff;
+}
+
+body pre
+{
+  margin: .75em 0;
+  line-height: 1.3;
+  color: #4f3f3f;
+  font-weight: bold;
+}
+
+body div
+{
+  margin: 0;
+}
+
+dl
+{
+  margin: .4em 0;
+  line-height: 1.2;
+}
+
+.legalnotice
+{
+  font-size: small;
+}
+
+h1,h2,h3,h4,h5,h6,
+div.example p b,
+.question,
+div.table p b,
+div.procedure p b
+{
+  color: #990000;
+}
+
+.option
+{
+  color: #0000ca;
+  font-weight: bold;
+}
+
+.parameter
+{
+  color: #007a00;
+  font-weight: bold;
+}
+
+a
+{
+  color: #000000;
+}
+
+a:hover
+{
+  color: #3c3c3c;
+  border-bottom: 1px solid #dc0000;
+}
+
+hr
+{
+  background-color: #9c9c9c;
+  border-style: none;
+  height: 1px;
+}
+
+li
+{
+  list-style-type: square;
+}
+
+.programlisting, .screen
+{
+  background-color: #F8F9FD;
+  border-color: #907777;
+  border-width: 1px;
+  border-style: solid;
+  padding: 0.5em;
+}
+

diff --git a/doc/cookbook/version.xml.in b/doc/cookbook/version.xml.in
new file mode 100644 (file)
index 0000000..dd16174
--- /dev/null
+++ b/doc/cookbook/version.xml.in
@@ -0,0 +1 @@
+@CLUTTER_API_VERSION@