cookbook: Added support for inline video

Amended Makefile to copy content of videos directory into
installation directories. Also copies videos and images
into the html/ directory during the build, so that the
built cookbook can be viewed locally (for testing without
having to install).

Added an XSLT template to transform Docbook <inlinemediaobject>
elements into HTML 5 <video> elements, with a fallback to
link to the video displayed for browsers without HTML 5 support.

Added note to "Contributing" appendix explaining how to put
video into a recipe.

doc/common/cookbook.xsl

@@ -0,0 +1,18 @@
+<?xml version="1.0"?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+  <xsl:include href="ref-html-style.xsl"/>
+
+  <xsl:template match="inlinemediaobject" priority="100">
+    <video controls="controls">
+      <xsl:attribute name="src"><xsl:value-of select="videoobject/videodata/@fileref"/></xsl:attribute>
+      <!-- fallback link to video for non-HTML 5 browsers -->
+      <a>
+        <xsl:attribute name="href">
+          <xsl:value-of select="videoobject/videodata/@fileref"/>
+        </xsl:attribute>
+        <xsl:apply-templates select="alt"/>
+      </a>
+    </video>
+  </xsl:template>
+
+</xsl:stylesheet>

doc/cookbook/Makefile.am

@@ -28,8 +28,14 @@ XSL_XHTML_URI = $(XSL_BASE_URI)/xhtml/docbook.xsl
 HTML_FILES = html/*.html
 CSS_FILES = html/*.css
 IMAGE_FILES = images/clutter-logo.png
+VIDEO_FILES = \
+	$(NULL)
 
-EXTRA_DIST = clutter-cookbook.xml.in $(IMAGE_FILES) $(XML_FILES)
+EXTRA_DIST = \
+	clutter-cookbook.xml.in \
+	$(IMAGE_FILES) \
+	$(XML_FILES) \
+	$(VIDEO_FILES)
 
 CLEANFILES = \
 	pdf-build.stamp \
@@ -42,9 +48,18 @@ pdf-build.stamp: clutter-cookbook.xml
 	&& echo timestamp > $(@F)
 
 html-build.stamp: clutter-cookbook.xml
+	if [ ! -d html ] ; then mkdir html ; fi && \
+	if [ ! -d html/images ] ; then mkdir html/images ; fi && \
+	if [ ! -d html/videos ] ; then mkdir html/videos ; fi && \
 	$(XSLTPROC) $(XSLTOPTS) -o clutter-cookbook.html $(XSL_XHTML_URI) $(top_builddir)/doc/cookbook/clutter-cookbook.xml && \
-	$(XSLTPROC) $(XSLTOPTS) -o html/ ref-html-style.xsl $(top_builddir)/doc/cookbook/clutter-cookbook.xml && \
+	$(XSLTPROC) $(XSLTOPTS) -o html/ cookbook.xsl $(top_builddir)/doc/cookbook/clutter-cookbook.xml && \
-  cp $(top_srcdir)/doc/common/style.css html/ && \
+	cp $(top_srcdir)/doc/common/style.css html/ && \
+	if [[ "$(VIDEO_FILES)" != "" ]] ; then \
+		for file in `ls $(VIDEO_FILES)`; do \
+			cp $$file html/videos/ ; \
+		done \
+	fi && \
+	cp images/* html/images/ && \
 	echo timestamp > $(@F)
 
 if ENABLE_PDFS
@@ -91,6 +106,17 @@ install-data-local:
 	    fi \
 	  done; \
 	fi; \
+	if [ -d ./videos ] && [[ "$(VIDEO_FILES)" != "" ]] ; \
+	then \
+	  $(mkinstalldirs) $(DESTDIR)$(TARGET_DIR)/videos ; \
+    for file in `ls $(VIDEO_FILES)`; do \
+      if [ -f $$file ]; \
+      then \
+        basefile=`echo $$file | sed -e 's,^.*/,,'`; \
+        $(INSTALL_DATA) $$file $(DESTDIR)$(TARGET_DIR)/videos/$$basefile; \
+      fi \
+    done; \
+	fi; \
 	$(INSTALL_DATA) html/clutter-cookbook.devhelp $(DESTDIR)$(TARGET_DIR)/clutter-cookbook.devhelp
 
 .PHONY : doc

doc/cookbook/clutter-cookbook.xml.in

@@ -60,7 +60,7 @@
       <listitem>
         <para>If adding a new recipe, use the
         <filename>recipe-template.xml</filename> XML file as a basis.
-        You can find it in the <filename>&lt;clutter_source&gt;/doc/cookbook/</filename>
+        You can find it in the <filename>&lt;clutter source&gt;/doc/cookbook/</filename>
         directory.</para>
       </listitem>
       <listitem>
@@ -103,6 +103,70 @@
         <para>Use the &lt;note&gt; element for asides which might
         otherwise interrupt the flow of the recipe.</para>
       </listitem>
+      <listitem>
+        <para>To include a video in a recipe, do the following:</para>
+        <itemizedlist>
+          <listitem>
+            <para>Make the video as short as is practical, and only include
+            the relevant Clutter window(s).</para>
+          </listitem>
+
+          <listitem>
+            <para>Use Ogg Theora for the encoding.</para>
+          </listitem>
+
+          <listitem>
+            <para>Put the file into the
+            <filename>&lt;clutter source&gt;/doc/cookbook/videos</filename>
+            directory. The name should be in the format
+            <filename>&lt;section&gt;-&lt;recipe&gt;-&lt;identifier&gt;.ogv</filename>.
+            For example: <filename>animations-fading-fade-out.ogv</filename>.</para>
+          </listitem>
+
+          <listitem>
+            <para>Add the name of the file to the <varname></varname>
+            in the cookbook's <filename>Makefile.am</filename>, e.g.</para>
+
+            <informalexample>
+              <programlisting>
+<![CDATA[
+VIDEO_FILES = \
+	videos/animations-fading-fade-out.ogv \
+	$(NULL)
+]]>
+              </programlisting>
+            </informalexample>
+
+            <para>This ensures it gets included in the distribution and
+            installation.</para>
+          </listitem>
+
+          <listitem>
+            <para>Use an &lt;inlinemediaobject&gt; to include it in the
+            Docbook recipe file. It should look something like this:</para>
+
+            <informalexample>
+              <programlisting>
+<![CDATA[
+<inlinemediaobject>
+  <videoobject>
+    <videodata fileref="videos/cookbook-animations-fading-in-then-out.ogv"/>
+  </videoobject>
+  <alt>
+    <para>Video showing an actor fading in then out using
+    <type>ClutterState</type></para>
+  </alt>
+</inlinemediaobject>
+]]>
+              </programlisting>
+            </informalexample>
+
+            <para>The &lt;alt&gt; tag provides the text which
+            is presented as a link to the file for users whose browser
+            doesn't support HTML 5 embedded video.</para>
+          </listitem>
+        </itemizedlist>
+      </listitem>
     </itemizedlist>
 
   </appendix>

doc/cookbook/videos/README

@@ -0,0 +1 @@
+Put videos for inclusion in cookbook (Ogg Theora, preferably) here.