path: root/slides/doc/slides.xml

<?xml version='1.0'?>

<dbs:slides	xmlns="http://docbook.org/ns/docbook"
		xmlns:dbs="http://docbook.org/ns/docbook-slides"
		xmlns:xlink="http://www.w3.org/1999/xlink">
  <info>
    <title>The DocBook Slides Extension</title>
    <titleabbrev>DocBook Slides</titleabbrev>
    <author>
      <personname>
	<firstname>Gábor</firstname>
	<surname>Kövesdán</surname>
      </personname>
      <affiliation>
        <orgname>The DocBook Project</orgname>
      </affiliation>
      <email>gabor@kovesdan.org</email>
    </author>
    <pubdate>3 Aug 2012</pubdate>
    <releaseinfo role="version">5.0</releaseinfo>
    <copyright>
      <year>2012</year>
      <holder>Gábor Kövesdán</holder>
    </copyright>
  </info>

  <dbs:foil dbs:style="introduction">
    <info>
      <title>Introduction</title>
    </info>

    <para>DocBook Slides ...</para>

    <itemizedlist>
      <listitem>
        <para>is a multi-namespace schema extension
	  to the original <link xlink:href="http://www.docbook.org/">DocBook</link>
	  <xref linkend="docbook5"/> schema.</para>
      </listitem>
      
      <listitem>
	<para>was originally created by
	  <personname><firstname>Norman</firstname><surname>Walsh</surname></personname>.</para>
      </listitem>
      
      <listitem>
	<para>and was later redesigned for DocBook 5.0 by
	  <personname><firstname>Gábor</firstname><surname>Kövesdán</surname></personname>.</para>
       </listitem>
     </itemizedlist>
     
     <para>This document serves for two purposes:</para>
     
    <itemizedlist>
      <listitem>
        <para>To explain DocBook Slides.</para>
      </listitem>
      
      <listitem>
	<para>To serve itself as a test document to demonstrate how
	  slides are marked up and how different output formats are
	  rendered.</para>
      </listitem>
     </itemizedlist>
  </dbs:foil>
  
  <dbs:foil>
    <info>
      <title>Basic Concepts</title>
    </info>
    
    <itemizedlist>
      <listitem>
        <para>DocBook is an XML <xref linkend="w3c-xml"/> grammar to mark up
	  papers and books and then process them with XML-related standards.
	  It concentrates on structure and semantics, not layout.</para>
      </listitem>
	
      <listitem>
        <para>DocBook Slides is an extension for DocBook to create
	  presentation slides.</para>
      </listitem>
      
      <listitem>
        <para>By nature, layout is part of a presentation but DocBook Slides
	  still focuses on structure and semantics.</para>
      </listitem>
      
      <listitem>
        <para>DocBook Slides uses almost the entire DocBook grammar and
	  provides only a minimal set of layout-controlling elements.
	  This keeps is simple and easy to use.</para>
      </listitem>
      
      <listitem>
        <para>And still, you can copy-paste, use XInclude, etc.</para>
      </listitem>
    </itemizedlist>
  </dbs:foil>

  <dbs:foilgroup>
    <info>
      <title>Features of DocBook Slides</title>
    </info>

    <para>Let's see some features of DocBook
      Slides.</para>

    <dbs:foil>
      <info>
	<title>Using Namespaces</title>
      </info>

      <para>DocBook Slides uses a separate namespace for its elements.
        This has various advantages:</para>
	
      <itemizedlist>
	<listitem>
	  <para>It isolates the extension elements and the original
	    DocBook schema does not have to know anything about them.</para>
	</listitem>
	
	<listitem>
	  <para>It also avoids name clashes and XML processors can easily
	    distinguish between the two set of elements.</para>
	</listitem>
	
	<listitem>
	  <para>This modular concept makes it easy to extend the official
	    stylesheets with specific processing.</para></listitem>
      </itemizedlist>
    </dbs:foil>

    <dbs:foil>
      <info>
        <title>Easy to Learn</title>
      </info>

      <para>If you already know and use DocBook, DocBook Slides is for you:</para>
      
      <itemizedlist>
        <listitem>
	  <para>You can use the usual inline and block elements when marking up
	    your text, you only have to learn a few new markup elements.</para>
	</listitem>
	
	<listitem>
	  <para>Also, you may include DocBook fragments with XInclude.
	    Imagine an important table that is part of your scientific
	    paper and you also want to show it on a conference.
	    You do not have to copy-paste it but you can just have it in
	    one single file that you later include in both documents.</para>
	</listitem>
      </itemizedlist>
    </dbs:foil>

    <dbs:foil>
      <info>
        <title>Development Status</title>
      </info>

      <itemizedlist>
        <listitem>
	  <para>DocBook Slides - just like DocBook - is an open source product
	    and it is under constant development and improvement.</para>
	</listitem>
	
	<listitem>
	  <para>The curently supported output formats are
	    plain XHTML, S5 XHTML <xref linkend="s5"/>,
	    W3C HTML Slidy <xref linkend="slidy"/> and XSL FO <xref linkend="w3c-xslfo"/>.
	    In the future, support for other important
	    output formats (e.g. HTML5, EPUB) may be added.</para>
	</listitem>
      </itemizedlist>
    </dbs:foil>
  </dbs:foilgroup>

  <dbs:foilgroup xml:id="introductionary-examples">
    <info>
      <title>Tutorial Examples</title>
    </info>

    <para>Let's see some basic examples.</para>

    <dbs:foil>
      <info>
        <title>A Minimal Markup 1</title>
      </info>

      <informalexample>
<programlisting>&lt;?xml version='1.0'?&gt;
&lt;dbs:slides xmlns="http://docbook.org/ns/docbook"
  xmlns:dbs="http://docbook.org/ns/docbook-slides"&gt; <co xml:id="co.slides"/>
  &lt;title&gt;Presentation Title&lt;/title&gt; <co xml:id="co.slides.title"/>
</programlisting>

	<calloutlist>
	  <callout arearefs="co.slides">
	    <para>The root element with proper namespace declarations.</para>
	  </callout>
	  
	  <callout arearefs="co.slides.title">
	    <para>It contains the title but can have more.</para>
	  </callout>
	</calloutlist>
      </informalexample>
    </dbs:foil>
    
    <dbs:foil>
      <info>
        <title>A Minimal Markup 2</title>
      </info>

      <informalexample>
<programlisting>
  &lt;dbs:foil&gt; <co xml:id="co.foil"/>
    &lt;title&gt;Foil Title&lt;/title&gt;
    &lt;para&gt;Foil content&lt;/para&gt; <co xml:id="co.foil.para"/>
  &lt;/dbs:foil&gt;
&lt;/dbs:slides&gt;</programlisting>
	<calloutlist>
	  <callout arearefs="co.foil">
	    <para>At least one foil obligatory.</para>
	  </callout>
	  
	  <callout arearefs="co.foil.para">
	    <para>A foil can contain any block element from DocBook.</para>
	  </callout>
	</calloutlist>
      </informalexample>
    </dbs:foil>
    
    <dbs:foil>
      <info>
        <title>The Whole Example</title>
      </info>

      <para>Let's see the whole markup together:</para>

      <informalexample>
<programlisting>&lt;?xml version='1.0'?&gt;
&lt;dbs:slides xmlns="http://docbook.org/ns/docbook"
  xmlns:dbs="http://docbook.org/ns/docbook-slides"&gt;
  &lt;title&gt;Presentation Title&lt;/title&gt;
  &lt;dbs:foil&gt;
    &lt;title&gt;Foil Title&lt;/title&gt;
    &lt;para&gt;Foil content&lt;/para&gt;
  &lt;/dbs:foil&gt;
&lt;/dbs:slides&gt;</programlisting>
      </informalexample>
    </dbs:foil>
    
    <dbs:foil>
      <info>
        <title>Grouping Foils</title>
      </info>
	
	<para>We can form groups of logical sets of foils and also add some
	  introductionary text for them.  In the rendered forms, these groups
	  can have a table of contents of the included slides.  You can also
	  see such groups in this presentation.</para>
	  
	<informalexample>
<programlisting><![CDATA[<dbs:foilgroup>
  <title>Group 1</title>
  
  <para>This is an introduction.</para>
  
  <dbs:foil>
  ...
  </dbs:foil>
</dbs:foilgroup>]]></programlisting>
      </informalexample>
    </dbs:foil>
  </dbs:foilgroup>
    
  <dbs:foilgroup>
    <info>
      <title>Markup Examples</title>
    </info>
    
    <para>Let's see how to create the particular foils with
      DocBook Slides.</para>
    
    <dbs:foil>
      <info>
	<title>Info Content</title>
      </info>
      
      <para>You can wrap the title into the <tag>&lt;info&gt;</tag> element that
        comes from the DocBook schema.  It also means you can
	add the usual authoring information here:</para>
	
	<informalexample>
<programlisting><![CDATA[
  <info>
    <title>Group 1</title>
    
    <author>
      <personname>
        <firstname>John</firstname>
        <surname>Doe</surname>
      </personname>
      <affiliation>FooBar Inc.</affiliation>
    </author>
    
    <copyright><year>2012</year></copyright>
  </info>]]></programlisting>
      </informalexample>
    </dbs:foil>

    <dbs:foil>
      <info>
        <title>Block Content</title>
      </info>

      <itemizedlist>
        <listitem>
	  <para>You have access to all of the block content elements in DocBook,
            e.g. you can create a simple paragraph with
	    <code>&lt;para&gt;</code>, just like in DocBook.</para>
	</listitem>
	
	<listitem>
	  <para>Or you can use lists, like <code>&lt;itemizedlist&gt;</code>.</para>
	</listitem>
      </itemizedlist>
      
      <programlisting>Or &lt;programlisting&gt; with some code or markup inside.</programlisting>
    </dbs:foil>
    
    <dbs:foil>
      <info>
        <title>Inline Content</title>
      </info>
      
      <itemizedlist>
        <listitem>
	  <para>Just like block elements, you can also use inline DocBook
	    elements to mark up your content on your foils.</para>
	</listitem>
	
	<listitem>
	  <para>For example, you can <emphasis>emphasize</emphasis>
	    something with <tag>&lt;emphasis&gt;</tag> or you
	    can mark <literal>literal</literal> text as such with
	    <tag>&lt;literal&gt;</tag>.</para>
	</listitem>
	
	<listitem>
	  <para>By the way, the inline markup citation above is marked up
	    with <tag>&lt;tag&gt;</tag>.</para>
	</listitem>
	
	<listitem>
	  <para>Apart from these, feel free to use the rest of
	    the markup elements.</para>
	</listitem>
      </itemizedlist>
    </dbs:foil>
    
    <dbs:foil>
      <info>
        <title>FAQ Listings</title>
      </info>
      
      <qandaset>
	<qandaentry>
	  <question>
	    <para>What else can I use to make my slides useful
	      and practical?</para>
	  </question>
	  
	  <answer>
	    <para>You can include some questions and answers with
	      <tag>&lt;qandaset&gt;</tag> and related elements to answer some
	      frequently asked questions.</para>
	  </answer>
	</qandaentry>
      </qandaset>
    </dbs:foil>
    
    <dbs:foil>
      <info>
        <title>References</title>
      </info>
      
      <itemizedlist>
        <listitem>
	  <para>Sometimes you need to add some remarks and some
	    references to your slide content.</para>
	</listitem>
	
	<listitem>
	  <para>For small remarks, you can use the
	    <code>&lt;footnote&gt;</code> element to insert a footnote
	    that will appear on the same foil where it is inserted.</para>
	</listitem>
	
	<listitem>
	  <para>Or for references to external content
	    - books and websites - you can include one or more
	    bibliography foils in the end.</para>
	</listitem>
	
	<listitem>
	  <para>On these foils, instead of the usual bulleted points, use the
	    <code>&lt;bibliography&gt;</code> element and you
	    will get a nicely formatted reference list.</para>
	</listitem>

	<listitem>
	  <para>Use <code>&lt;xref&gt;</code> in the content
	    to generate a link to the reference entry.</para>
	</listitem>
      </itemizedlist>
    </dbs:foil>
    
    <dbs:foil dbs:incremental="1">
      <info>
        <title>Incremental Slides</title>
      </info>
      
      <itemizedlist>
        <listitem>
	  <para>If you set the <code>dbs:incremental</code> attribute ...</para>
	</listitem>
	
	<listitem>
	  <para>... to <literal>1</literal> on a foil, ...</para>
	</listitem>
	
	<listitem>
	  <para>... then you will get incremental lists, ...</para>
	</listitem>
	
	<listitem>
	  <para>... like this if they are supported in the output format. (XHTML-based)</para>
	</listitem>
      </itemizedlist>
    </dbs:foil>
    
    <dbs:foil dbs:collapsible="1">
      <info>
        <title>Collapsible Lists</title>
      </info>

      <para>You can see a collapsible list below (depending on the output
        format).  Click on the node to expand it.</para>

      <orderedlist>
        <listitem>
          <orderedlist>
          <listitem>
            <para>If you set the <code>dbs:collapsible</code> attribute ...</para>
        </listitem>

        <listitem>
          <para>... to <literal>1</literal> on a foil, ...</para>
        </listitem>

        <listitem>
          <para>... then you will get collapsible lists, ...</para>
        </listitem>

        <listitem>
          <para>... like this if they are supported in the output format. (Slidy)</para>
        </listitem>
      </orderedlist>
        </listitem>
      </orderedlist>
    </dbs:foil>
    
    <dbs:foil>
      <info>
        <title>Building Blocks</title>
      </info>

      <itemizedlist>
        <listitem>
	  <para>Slides are layout-oriented documents; formatting
	    is a crucial part of them.</para>
	</listitem>
	
	<listitem>
	  <para>DocBook aims to separate structure and layout but for
	    Slides sometimes it is not entirely possible, yet the
	    layout-related markup is tried to be kept minimal.</para>
	</listitem>
	
	<listitem>
	  <para>You can use the <tag>&lt;dbs:block&gt;</tag> element
	    that will be transformed to a container type in the
	    generated document (e.g. <tag>&lt;div&gt;</tag> in HTML).</para>
	</listitem>
	
	<listitem>
	  <para>You can also apply the <literal>dbs:style</literal> attribute
	    to blocks and you can even embed them into each other.</para>
	</listitem>
	
	<listitem>
	  <para>Use CSS or extend the XSLT stylesheets to control
	    renering of your custom blocks.</para>
	</listitem>
      </itemizedlist>
    </dbs:foil>
    
    <dbs:foil>
      <info>
        <title>Block Example</title>
      </info>

      <dbs:block dbs:style="left">
        <para>This is the left block.</para>
      </dbs:block>
      
      <dbs:block dbs:style="right" dbs:incremental="1">
        <para>This is the right block.  And it is marked incremental.</para>
      </dbs:block>  
    </dbs:foil>
  </dbs:foilgroup>
  
  <dbs:foilgroup>
    <title>Images and Formulas</title>
    
    <dbs:foil>
      <info>
        <title>Incremental Images</title>
      </info>
      
      <para>This is only supported in XHTML-based output.</para>

      <dbs:block dbs:incremental="1" dbs:style="face_container">
        <mediaobject>
          <imageobject>
	    <imagedata dbs:style="face_first" fileref="images/face1.gif"/>
	  </imageobject>
        </mediaobject>

        <mediaobject>
          <imageobject>
	    <imagedata dbs:style="face_other" fileref="images/face2.gif"/>
  	  </imageobject>
        </mediaobject>

        <mediaobject>	
          <imageobject>
	    <imagedata dbs:style="face_other" fileref="images/face3.gif"/>
	  </imageobject>
        </mediaobject>

        <mediaobject>
          <imageobject>
	    <imagedata dbs:style="face_other" fileref="images/face4.gif"/>
	  </imageobject>
        </mediaobject>
      </dbs:block>
    </dbs:foil>
    
    <dbs:foil>
      <info>
        <title>Embedded SVG</title>
      </info>
      
      <para>You can embed SVG
        <footnote><para>See <uri xlink:href="http://www.w3.org/TR/SVG11/">http://www.w3.org/TR/SVG11/</uri>.</para></footnote>
        code, like this:</para>
      
      <programlisting><![CDATA[<svg xml:id="circle" 
				    xmlns="http://www.w3.org/2000/svg"
				    version="1.1">
  <circle cx="100" cy="50" r="40" stroke="black"
    stroke-width="2" fill="yellow" />
</svg>]]></programlisting>

      <svg xml:id="circle" xmlns="http://www.w3.org/2000/svg" version="1.1">
        <circle cx="100" cy="50" r="40" stroke="black" stroke-width="2" fill="yellow" />
      </svg> 
    </dbs:foil>
    
    <dbs:foil>
      <info>
        <title>Embedded MathML</title>
      </info>
      
      <para>You can embed MathML
        <footnote><para>See <uri xlink:href="http://www.w3.org/TR/MathML3/">http://www.w3.org/TR/MathML3/</uri>.</para></footnote>
	code, like this:</para>
      
      <programlisting><![CDATA[<math xml:id="identity-matrix-2dim"
				     xmlns="http://www.w3.org/1998/Math/MathML">
  <matrix>
    <matrixrow><cn>1</cn><cn>0</cn></matrixrow>
    <matrixrow><cn>0</cn><cn>1</cn></matrixrow>
  </matrix>
</math>]]></programlisting>

      <math xml:id="identity-matrix-2dim" xmlns="http://www.w3.org/1998/Math/MathML">
	<matrix>
	  <matrixrow><cn>1</cn><cn>0</cn></matrixrow>
	  <matrixrow><cn>0</cn><cn>1</cn></matrixrow>
	</matrix>
      </math>
    </dbs:foil>
  </dbs:foilgroup>

  <dbs:foilgroup>
    <info>
      <title>Presentation</title>
    </info>
    
    <dbs:foil>
      <info>
        <title>Available Formats</title>
      </info>
      
      <informaltable>
	<tgroup cols="2">
	  <thead>
	    <row><entry>Stylesheet</entry><entry>Description.</entry></row>
	  </thead>

          <tbody>
	    <row>
	      <entry>xhtml/plain.xsl</entry>
	      <entry>Single plain XHTML file.</entry>
	    </row>

	    <row>
	      <entry>xhtml/slidy.xsl</entry>
	      <entry>Single XHTL file in W3C HTML Slidy format.</entry>
	    </row>

	    <row>
	      <entry>xhtml/s5.xsl</entry>
	      <entry>Single XHTML file in S5 format.</entry>
	    </row>

	    <row>
	      <entry>fo/plain.xsl</entry>
	      <entry>XSL Formatting Objects for printed output.</entry>
	    </row>
	    
	  </tbody>
	</tgroup>
      </informaltable>
    </dbs:foil>
    
    <dbs:foil>
      <info>
        <title>Plain XHTML</title>
      </info>
      
      <itemizedlist>
        <listitem>
	  <para>It is a simple plain <acronym>XHTML</acronym> output with
	    some classes given on the elements.  These let you create your
	    own CSS stylesheet for the rendering.</para>
	</listitem>
	
	<listitem>
	  <para>It is actually quite similar to the
	    <acronym>S<superscript>5</superscript></acronym> format with
	    <acronym>S<superscript>5</superscript></acronym>-specific
	    parts removed.  The objective with this format was simplicity
	    and <acronym>S<superscript>5</superscript></acronym>
	    already achieves that quite well but in case you do not want
	    to use that framework, you can create your own one.</para>
	</listitem>
	
	<listitem>
	  <para>The stylesheet to choose for this format is
	    <filename>xhtml/plain.xsl</filename>.</para>
	</listitem>
      </itemizedlist>
    </dbs:foil>
    
    <dbs:foil>
      <info>
        <title>W3C HTML Slidy</title>
      </info>
      
      <itemizedlist>
        <listitem>
	  <para>W3C <uri xlink:href="http://www.w3.org/Talks/Tools/Slidy2/">HTML Slidy</uri>
	    is an XHTML framework for presentations.</para>
	</listitem>
	
	<listitem>
	  <para>It seems mature and well maintained.</para>
	</listitem>
	
	<listitem>
	  <para>HTML Slidy handles well long content.  Its formatting
	    allows more text on a single foil and even if your text
	    overflows, you can scroll inside the single foil.  It also
	    supports collapsible lists and a JavaScript clock so that you
	    do not run out of time.</para>
	</listitem>
	
	<listitem>
	  <para>For HTML Slidy, use
	    <filename>xhtml/slidy.xsl</filename>.</para>
	</listitem>
      </itemizedlist>
    </dbs:foil>
    
    <dbs:foil>
      <info>
        <title>S5 Format</title>
      </info>
      
      <itemizedlist>
        <listitem>
	  <para><acronym xlink:href="http://meyerweb.com/eric/tools/s5/">S<superscript>5</superscript></acronym>
	    stands for <emphasis>Simple Standards-Based Slide Show System</emphasis>.</para>
	</listitem>
	
	<listitem>
	  <para>It is yet another XHTML-based framework for slideshows, like
	    HTML Slidy.</para>
	</listitem>
	
	<listitem>
	  <para>Its JavaScript code behaves somewhat differently and it is less
	    mature.</para>
	</listitem>
	
	<listitem>
	  <para>It supports incremental lists but in general, it is not so
	    feature-rich as HTML Slidy.</para>
	</listitem>
	
	<listitem>
	  <para>To create your <acronym>S<superscript>5</superscript></acronym>
	     presentation, pick the
	    <filename>xhtml/s5.xsl</filename> stylesheet.</para>
	</listitem>
      </itemizedlist>
    </dbs:foil>
    
    <dbs:foil>
      <info>
        <title>XSL FO Format</title>
      </info>
      
      <itemizedlist>
        <listitem>
	  <para>XSL FO is an XML vocabulary to describe how formatted
	    output is presented.</para>
	</listitem>
	
	<listitem>
	  <para>It is used here as an intermediate format between DocBook Slides
	    and printable output.</para>
	</listitem>
	
	<listitem>
	  <para>First, generate the XSL FO document.</para>
	</listitem>
	
	<listitem>
	  <para>Then use your XSL FO processor to render your printable
	    document in PDF, PostScript, etc. depending on the capabilities of
	    the software you use.</para>
	</listitem>
	
	<listitem>
	  <para>If you need a free processor, take a look at
	    Apache FOP <xref linkend="fop"/>.</para>
	</listitem>
      </itemizedlist>
    </dbs:foil>
    
    <dbs:foil>
      <info>
        <title>XSLT Parameters</title>
      </info>

      <itemizedlist>
	<listitem>
	  <para>The provided stylesheets offer XSLT <xref linkend="w3c-xslt"/> parameters
	    to adjust some tunables of the output generation.</para>
	</listitem>
	
	<listitem>
	  <para>The parameters are documented in the documentation
	    that accompanies the DocBook XSL distribution.</para>
	</listitem>
	
	<listitem>
	  <para>All the DocBook Slides stylesheets are extensions of the
	    original DocBook stylesheets so adjusting their parameters may also
	    affect your rendered slides.</para>
	</listitem>
      </itemizedlist>
    </dbs:foil>
     
    <dbs:foil>
      <info>
        <title>Customizations</title>
      </info>
      
      <para>Sometimes parameters are not enough and you need to modify
        the templates to achieve your goal.  Customizations are easy
	to create with XSLT.</para>

      <orderedlist>
	<listitem>
	  <para>Just pick up a stylesheet that you want to customize.</para>
	</listitem>
	
	<listitem>
	  <para>Create a new, empty stylesheet that imports the original
	    one.</para>
	</listitem>
	
	<listitem>
	  <para>Override the original templates that do not work
	    in the way you desire.</para>
	</listitem>
	
	<listitem>
	  <para>Of course, this requires some knowledge in XSLT and
	    you will need to read the code to see what to override.</para>
	</listitem>
      </orderedlist>
    </dbs:foil>
  </dbs:foilgroup>
  
  <dbs:foilgroup>
    <info>
      <title>Authoring with DocBook Slides 5.0</title>
    </info>
    
    <dbs:foil>
      <info>
        <title>Choosing a Validator</title>
      </info>
      
      <itemizedlist>
        <listitem>
	  <para>Once you have some slides marked up in DocBook Slides,
	    you probably want to make sure your markup is valid. Otherwise,
	    it is not guaranteed that the output will be generated properly.
	    For this, you need a validator.</para>
	</listitem>
	
	<listitem>
	  <para>The DocBook Slides schema is described in the RELAX-NG grammar language.</para>
	</listitem>
	
	<listitem>
	  <para>The recommended RELAX-NG validator is
	    <application>jing</application> <xref linkend="jing"/>.</para>
	</listitem>
	
	<listitem>
	  <para>Alternatively, you can use <application>Emacs/nXML</application>
	    with the supplied <filename>locatingrules.xml</filename> file.</para>
	</listitem>
      </itemizedlist>
      
      <warning>
        <para>The RELAX-NG validation in the xmllint program from libxml2 is known to have
	  bugs and does not work correctly with DocBook Slides.</para>
      </warning>
    </dbs:foil>
    
    <dbs:foil>
      <info>
        <title>Validating Slides</title>
      </info>
      
      <itemizedlist>
        <listitem>
	  <para>With <command>jing</command>, run:
	    <userinput>jing ~/docbook-slides/slides.rng foo.xml</userinput>.</para>
	</listitem>
	
	<listitem>
	  <para>For <application>Emacs/nXML</application>, you can put the following into
	    your <filename>emacs.conf</filename>:</para>
	    
	  <programlisting>
      (setq rng-schema-locating-files
        (append
          '("~/docbook-slides/locatingrules.xml")))</programlisting>
	  
	  <para>Or you can do <userinput>M-x customize-variable rng-schema-locating-files</userinput>
	    and then add the absolute path to the file.</para>
	</listitem>
      </itemizedlist>
    </dbs:foil>
    
    <dbs:foil>
      <info>
        <title>Transforming DocBook Slides Documents</title>
      </info>
      
      <itemizedlist>
        <listitem>
	  <para>You need an XSLT processor to transform the documents.
	    For example, you can use either <command>xsltproc</command> from
	    <application>libxslt</application> <xref linkend="libxslt"/>, <application>Xalan</application>
	    or <application>Saxon</application>.</para>
	</listitem>
	
	<listitem>
	  <para>It is recommended to use <command>xsltproc</command>, since
	    it is significantly faster than the other two and the DocBook Slides
	    stylesheets were also tested with it.</para>
	</listitem>
	
	<listitem>
	  <para>Pick the proper stylesheet for your chosen output format.
	    For example, it is <filename>xhtml/slidy.xsl</filename> for
	    HTML Slidy.</para>
	</listitem>
	
	<listitem>
	  <para>Type: <userinput>xsltproc xsl/slides/xhtml/slidy.xsl foo.xml &gt; foo.html</userinput></para>
	</listitem>
      </itemizedlist>
    </dbs:foil>
  
    <dbs:foil>
      <info>
        <title>Rendering Printable Output</title>
      </info>
      
      <itemizedlist>
        <listitem>
	  <para>First create the XSL FO document with XSLT:
	    <userinput>xsltproc xsl/slides/fo/plain.xsl foo.xml &gt; foo.fo</userinput></para>
	</listitem>
	
	<listitem>
	  <para>Then use your XSL FO processor to render the final document.</para>
	</listitem>
	
	<listitem>
	  <para>For example, to render a PDF with Apache FOP, type:
	    <userinput>fop foo.fo foo.pdf</userinput></para>
	</listitem>
      </itemizedlist>
    </dbs:foil>
  </dbs:foilgroup>
  
  <dbs:foilgroup>
    <info>
      <title>DocBook Slides Limitations</title>
    </info>
    
    <dbs:foil>
      <info>
        <title>Foil Content</title>
      </info>
      
      <para>Creating slides is quite different from creating
        papers and books.</para>
      
      <itemizedlist>
        <listitem>
	  <para>Presentational slide are layout-oriented by nature as opposed to DocBook, which is
	    structure-oriented. The content of the foil must fit but there
	    is no easy way to detect this so this should be checked
	    and controlled manually.</para>
	</listitem>
	
	<listitem>
	  <para>Formatting of slide content is not necessarily consistent but part
	    of the design of each foil and illustration used in
	    the presentation, while an important principle of
	    DocBook is separating content and styling.  To achieve
	    something very unique, you will probably need heavy
	    customization.</para>
	</listitem>
      </itemizedlist>
    </dbs:foil>
    
    <dbs:foil>
      <info>
        <title>Animations and Sound Effects</title>
      </info>
      
      <para>DocBook was invented for mostly printed or web
        content, while slides are rarely presented in a
	printed form.</para>
	
      <itemizedlist>
	<listitem>
	  <para>Slides are usually shown on computer screen or
	    projector and may heavily use animated or audio content
	    to support the presentations.</para>
	</listitem>
	
	<listitem>
	  <para>Most of the possible output formats are usually
	    used in printed form or on the web.  The first lacks
	    the possibility of animated and audio content and the
	    second one lacks good open standards for doing so.</para>
	</listitem>
	
	<listitem>
	  <para>Maybe a future HTML5 or OpenDocument support
	    can bring in some new features but for now, you cannot
	    really use animations and sound.</para>
	</listitem>
      </itemizedlist>
    </dbs:foil>
  </dbs:foilgroup>
  
  <dbs:foilgroup>
    <info>
      <title>Frequently Asked Questions</title>
    </info>
    
    <dbs:foil>
      <info>
        <title>Compatibility</title>
      </info>
      
      <qandaset>
	<qandaentry>
	  <question>
	    <para>Is DocBook Slides 5.0 stylesheets compatible with
	      older versions of DocBook Slides or vice versa?</para>
	  </question>
	  
	  <answer>
	    <para>Not at all, since it is heavily redesigned.  But
	      you can find an XSLT transformation in the
	      <filename class="directory">tools/</filename>
	      directory, which can convert your slides to the new
	      schema.</para>
	  </answer>
	</qandaentry>
      </qandaset>
    </dbs:foil>
    
    <dbs:foil>
      <info>
        <title>Contribution</title>
      </info>

      <qandaset>
	<qandaentry>
	  <question>
	    <para>Can I contribute to the schema or to the stylesheets?</para>
	  </question>
	  
	  <answer>
	    <para>Of course, any contribution that can be useful for
	      other users and fits the concept of DocBook Slides
	      is more than welcome.</para>
	  </answer>
	</qandaentry>

	<qandaentry>
	  <question>
	    <para>What to do with my contribution?</para>
	  </question>
	  
	  <answer>
	    <para>Please first ask review on
	    the <link xlink:href="mailto:docbook-apps@lists.oasis-open.org">docbook-apps
	    mailing list</link> and users and other developers will tell you
	    what to improve and how to submit your work for inclusion.</para>
	  </answer>
	</qandaentry>
      </qandaset>
    </dbs:foil>
    
    <dbs:foil>
      <info>
        <title>Help</title>
      </info>

      <qandaset>
	<qandaentry>
	  <question>
	    <para>How can I get help in using the schema and the
	      accompanying stylesheets?</para>
	  </question>
	  
	  <answer>
	    <para>There is a
	    <link xlink:href="mailto:docbook-apps@lists.oasis-open.org">docbook-apps
	    mailing list</link> for general questions on DocBook and related
	    technologies.  There are numerous users and developers subscribed to
	    this list, so probably you can get help there.</para>
	  </answer>
	</qandaentry>
      </qandaset>
    </dbs:foil>
  </dbs:foilgroup>
  
  <dbs:foilgroup>
    <info>
      <title>Mini-Reference</title>
    </info>
    
    <para>Here you have the short and informal description of the DocBook
      Slides elements.  It is not meant to be a full and formalized
      referenced but rather a cheatsheet to look at.</para>
      
    <dbs:foil>
      <info>
        <title>dbs:slides</title>
      </info>
      
      <itemizedlist>
        <listitem>
	  <para><emphasis>May contain:</emphasis> db:title, db:titleabbrev,
	    db:subtitle, db:info, dbs:foilgroup, dbs:foil</para>
	</listitem>
	
	<listitem>
	  <para><emphasis>Usage:</emphasis> It is the root element that encloses the authoring
	    info and the particular foils that may be grouped to foil
	    groups.</para>
	</listitem>
      </itemizedlist>
    </dbs:foil>
    
    <dbs:foil>
      <info>
        <title>dbs:foilgroup</title>
      </info>
      
      <itemizedlist>
        <listitem>
	  <para><emphasis>May contain:</emphasis> db:title, db:titleabbev,
	    db:subtitle, db:info, [block content], dbs:foil, dbs:speakernotes,
	    dbs:handoutnotes</para>
	</listitem>
	
	<listitem>
	  <para><emphasis>Usage:</emphasis> It groups together various foils.  It can have its own info
	    section and an optional introductionary text.  Depending on your XSLT
	    parameters, it may generate a table of contents of enclosed foils.
	    Its usage is not obligatory but may be very useful for grouping together
	    logically related foils.  It may have some speaker notes and handout notes, as well.</para>
	</listitem>
      </itemizedlist>
    </dbs:foil>
    
    <dbs:foil>
      <info>
        <title>dbs:foil</title>
      </info>
      
      <itemizedlist>
        <listitem>
	  <para><emphasis>May contain:</emphasis> db:title, db:titleabbev,
	    db:subtitle, db:info, [block content], dbs:speakernotes,
	    dbs:handoutnotes</para>
	</listitem>
	
	<listitem>
	  <para><emphasis>Usage:</emphasis> It marks up a single foil.  Use
	    DocBook block elements to mark up your content.  It may have some speaker
	    notes and handout notes, as well.</para>
	</listitem>
      </itemizedlist>
    </dbs:foil>
    
    <dbs:foil>
      <info>
        <title>dbs:block</title>
      </info>
      
      <itemizedlist>
        <listitem>
	  <para><emphasis>May contain:</emphasis> [block content]</para>
	</listitem>
	
	<listitem>
	  <para><emphasis>Usage:</emphasis> It divides the content into layout units
	    that can later processed in a specific way.</para>
	</listitem>
      </itemizedlist>
    </dbs:foil>
    
     <dbs:foil>
      <info>
        <title>dbs:speakernotes</title>
      </info>
      
      <itemizedlist>
        <listitem>
	  <para><emphasis>May contain:</emphasis> [block content]</para>
	</listitem>
	
	<listitem>
	  <para><emphasis>Usage:</emphasis> Notes that are not meant to be presented to
	    the audience but to the speaker.</para>
	</listitem>
      </itemizedlist>
    </dbs:foil>

     <dbs:foil>
      <info>
        <title>dbs:handoutnotes</title>
      </info>
      
      <itemizedlist>
        <listitem>
	  <para><emphasis>May contain:</emphasis> [block content]</para>
	</listitem>
	
	<listitem>
	  <para><emphasis>Usage:</emphasis> Notes that are not to accompany
	    printed slides.</para>
	</listitem>
      </itemizedlist>
    </dbs:foil>
    
     <dbs:foil>
      <info>
        <title>Attribute dbs:incremental</title>
      </info>
      
      <itemizedlist>
        <listitem>
	  <para><emphasis>Usage:</emphasis> Makes the content incremental.
	    Allowed on any element and inherited to child elements
	    but not applicable everywhere and its effect depends on the output
	    format.</para>
	</listitem>
      </itemizedlist>
    </dbs:foil>
    
     <dbs:foil>
      <info>
        <title>Attribute dbs:collapsible</title>
      </info>
      
      <itemizedlist>
        <listitem>
	  <para><emphasis>Usage:</emphasis> Makes the content collapsible.
	    Allowed on any element and inherited to child elements
	    but not applicable everywhere and its effect depends on the output
	    format.</para>
	</listitem>
      </itemizedlist>
    </dbs:foil>
    
     <dbs:foil>
      <info>
        <title>Attribute dbs:style</title>
      </info>
      
      <itemizedlist>
        <listitem>
	  <para><emphasis>Usage:</emphasis> Classifies the given element
	    to a specific formatting class.  Typically applicable to foils,
	    foilgroups and mediaobject.  Allowed anywhere but not processed
	    everywhere.  In HTML it naturally maps to the <literal>class</literal>
	    attribute.</para>
	</listitem>
      </itemizedlist>
    </dbs:foil>
  </dbs:foilgroup>
  
  <dbs:foil>
    <info>
      <title>Related Standards</title>
    </info>
    
    <bibliography>
      <title>Related Standards</title>

      <biblioentry xml:id="w3c-xml">
        <title>Extensible Markup Language (XML)</title>

        <org>
          <orgname>W3C</orgname>
        </org>

        <bibliosource class="uri" xlink:href="http://www.w3.org/TR/REC-xml/">http://www.w3.org/TR/REC-xml/</bibliosource>
      </biblioentry>

      <biblioentry xml:id="docbook5">
        <title>The DocBook Schema Version 5.0</title>

        <org>
          <orgname>OASIS</orgname>
        </org>

        <bibliosource class="uri" xlink:href="http://docs.oasis-open.org/docbook/specs/docbook-5.0-spec-os.html">http://docs.oasis-open.org/docbook/specs/docbook-5.0-spec-os.html</bibliosource>
      </biblioentry>
      
      <biblioentry xml:id="w3c-xslt">
        <title>XSL Transformations (XSLT) Version 1.0</title>

        <org>
          <orgname>W3C</orgname>
        </org>

        <bibliosource class="uri" xlink:href="http://www.w3.org/TR/xslt">http://www.w3.org/TR/xslt</bibliosource>
      </biblioentry>
      
      <biblioentry xml:id="w3c-xslfo">
        <title>Extensible Stylesheet Language (XSL) Version 1.1</title>

        <org>
          <orgname>W3C</orgname>
        </org>

        <bibliosource class="uri" xlink:href="http://www.w3.org/TR/xsl/">http://www.w3.org/TR/xsl/</bibliosource>
      </biblioentry>
    </bibliography>
  </dbs:foil>
  
  <dbs:foil>
    <info>
      <title>Supported HTML Presentation Frameworks</title>
    </info>
    
    <bibliography>
      <title>Supported HTML Presentation Frameworks</title>

      <biblioentry xml:id="s5">
        <title>S<superscript>5</superscript></title>
	<subtitle>A Simple Standards-Based Slide Show System</subtitle>

        <bibliosource class="uri" xlink:href="http://meyerweb.com/eric/tools/s5/">http://meyerweb.com/eric/tools/s5/</bibliosource>
      </biblioentry>

      <biblioentry xml:id="slidy">
        <title>HTML Slidy</title>
	<subtitle>Slide Shows in HTML and XHTML</subtitle>

        <bibliosource class="uri" xlink:href="www.w3.org/Talks/Tools/Slidy2/">www.w3.org/Talks/Tools/Slidy2/</bibliosource>
      </biblioentry>
    </bibliography>
  </dbs:foil>
  
  <dbs:foil>
    <info>
      <title>Recommended Tools</title>
    </info>
    
    <bibliography>
      <title>Recommended Tools</title>

      <biblioentry xml:id="jing">
        <title>Jing RELAX-NG validator</title>

        <bibliosource class="uri" xlink:href="http://www.thaiopensource.com/relaxng/jing.html">http://www.thaiopensource.com/relaxng/jing.html</bibliosource>
      </biblioentry>

      <biblioentry xml:id="libxslt">
        <title>libxslt</title>
	<subtitle>The XSLT C library for GNOME</subtitle>

        <bibliosource class="uri" xlink:href="http://xmlsoft.org/xslt/">http://xmlsoft.org/xslt/</bibliosource>
      </biblioentry>
      
      <biblioentry xml:id="fop">
        <title>Apache FOP</title>

        <bibliosource class="uri" xlink:href="http://xmlgraphics.apache.org/fop/">http://xmlgraphics.apache.org/fop/</bibliosource>
      </biblioentry>
    </bibliography>
  </dbs:foil>
</dbs:slides>