Merge remote branch 'elliot/cookbook-include-videos'

* elliot/cookbook-include-videos:
  cookbook: Tweak so that videos sit inside a paragraph for better spacing
  docs: Note the P_() macro in the HACKING file
  cookbook: Added support for inline video

Conflicts:
	doc/cookbook/Makefile.am

doc/common/cookbook.xsl

@@ -0,0 +1,20 @@
+<?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">
+    <p>
+      <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>
+    </p>
+  </xsl:template>
+
+</xsl:stylesheet>

doc/cookbook/Makefile.am

@@ -33,7 +33,11 @@ VIDEO_FILES = \
 	videos/animations-fading-in-then-out.ogv \
 	$(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 \
@@ -46,9 +50,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 && \
-  cp $(top_srcdir)/doc/common/style.css html/ && \
+	$(XSLTPROC) $(XSLTOPTS) -o html/ cookbook.xsl $(top_builddir)/doc/cookbook/clutter-cookbook.xml && \
+	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
@@ -95,6 +108,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.