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.
This commit is contained in:
Elliot Smith 2010-07-15 13:27:02 +01:00
parent fd27ca7398
commit 1d9c64ff16
4 changed files with 113 additions and 4 deletions

18
doc/common/cookbook.xsl Normal file
View File

@ -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>

View File

@ -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 && \
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
@ -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

View File

@ -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>

View File

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