docbook-slides - basic distribution howto
-----------------------------------------

DocBook Slides provides customization layers of the both the
Simplified and the full DocBook XML DTD, as well as the DocBook XSL
Stylesheets. This package contains the XML document type definition
and stylesheets for processing DocBook Slides XML. The slides doctype
and stylesheets are for generating presentations, primarily in HTML.

Information on generating HTML slides from the source XML document are
given below.

0. Using Processing Instructions in Your Source Document:
=========================================================

In lieu of setting parameters in the xsl stylesheets, you might wish
to set a few of them in the source document itself. You may do this
using what are known as XML Processing Instructions, or PIs, for
short. Parameters that you may set with this method include:

       - graphics-dir
       - css-stylesheet-dir
       - script-dir

  The 'graphics-dir' parameter refers to the 'graphics' directory
  included in the package.

  The 'css-stylesheet-dir' and the 'script-dir' both (by default)
  correspond to the 'browser' directory included in the package.

To set these parameters using PIs, you might start your document as
follows:

<?xml version='1.0'?>
<!DOCTYPE slides 
     PUBLIC "-//Norman Walsh//DTD Slides XML V3.4.0//EN"
     "http://docbook.sourceforge.net/release/slides/3.4.0/schema/dtd/slides.dtd">
<?dbhtml graphics-dir="graphics" css-stylesheet-dir="browser"?>
<?dbhtml script-dir="browser"?>

The paths to the directories in the PIs should be specified relative
to the location of the HTML output files.

** Note that you should copy these directories from their installed
   locations in /usr/share/xml/docbook/slides/3.4.0/ to the location
   where you build your slide presentation.


I. To Compose Slides That Use The (Default) Simplified Docbook DTD:
===================================================================

Use the following prolog to create a source document based on a
customization of the Simplified DocBook DTD (~100 elements), rather
than the full DocBook XML DTD (~380 elements). This version should be
sufficient for most presentations.


<?xml version="1.0"?>
<!DOCTYPE slides
     PUBLIC "-//Norman Walsh//DTD Slides XML V3.4.0//EN"
     "http://docbook.sourceforge.net/release/slides/3.4.0/schema/dtd/slides.dtd">
<slides>
  ...
</slides>


II. To Compose Slides Using The Full DocBook XML DTD:
=====================================================

Use the following prolog to create a source document based on the full
DocBook XML DTD. Using this DTD will give you full access to most of
the ~380 elements in the DocBook XML V4.2 DTD. This DTD/prolog would
be useful, e.g., if you plan to use a number of programming constructs
in your slide presentation.


<?xml version="1.0"?>
<!DOCTYPE slides
     PUBLIC "-//Norman Walsh//DTD Slides Full XML V3.4.0//EN"
     "http://docbook.sourceforge.net/release/slides/3.4.0/schema/dtd/slides-full.dtd">
<slides>
  ...
</slides>


III. Generating HTML Slides From Your XML Source Document:
=========================================================

First, you must choose a style for your presentation, and hence a
stylesheet for processing your slides: 

* slides.xsl produces basic slides in HTML, one page per slide.

* frames.xsl produces slides in HTML using frames.

* tables.xsl produces slides in HTML using tables, one page per slide.

* w3c.xsl produces basic slides in HTML, one page per slide, using a
  navigation style similar to that of most W3C talks.

You will also wish to further customize your slides by setting some
parameters for the XSL stylesheets. See the package documentation for
the list of available parameters, or take a peek at
/usr/share/xml/docbook/slides/3.4.0/xsl/html/xsl/html/param.xsl.


To generate slides from xsltproc, with frames and setting the overlay
logo for the ToC frame, you would issue a command like:


xsltproc --stringparam overlay.logo http://docbook.sourceforge.net/release/buttons/slides-1.png \
	 /usr/share/xml/docbook/slides/3.4.0/xsl/html/frames.xsl sourcefile.xml


In addition to the documentation included with this package, you may
wish to download the slides-demo package, which provides examples of
each style of slide presentation. The slides-demo package can be
downloaded from http://sourceforge.net/projects/docbook. I may also
package the slides-demo as an rpm, if there is sufficient demand.


Feel free to offer comments, suggestions, or complaints.

     Mark


 -- Mark Johnson <mjohnson@redhat.com>, Wed Sep  8 16:15:00 EDT 2004
 --update: Ondrej Vasik <ovasik@redhat.com, Thu May 24 2007 for version 3.4.0