# The DocBook Slides Extension

DocBook Slides
Gábor
Kövesdán
The DocBook Project
gabor@kovesdan.org
3 Aug 2012
5.0
2012
Gábor Kövesdán

# Introduction

DocBook Slides ...

- is a multi-namespace schema extension to the original DocBook schema.

- was originally created by Norman Walsh.

- and was later redesigned for DocBook 5.0 by Gábor Kövesdán.

This document serves for two purposes:

- To explain DocBook Slides.

- To serve itself as a test document to demonstrate how slides are marked up and how different output formats are rendered.

# Basic Concepts

- DocBook is an XML grammar to mark up papers and books and then process them with XML-related standards. It concentrates on structure and semantics, not layout.

- DocBook Slides is an extension for DocBook to create presentation slides.

- By nature, layout is part of a presentation but DocBook Slides still focuses on structure and semantics.

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

- And still, you can copy-paste, use XInclude, etc.

# Features of DocBook Slides

Let's see some features of DocBook Slides.

# Using Namespaces

DocBook Slides uses a separate namespace for its elements. This has various advantages:

- It isolates the extension elements and the original DocBook schema does not have to know anything about them.

- It also avoids name clashes and XML processors can easily distinguish between the two set of elements.

- This modular concept makes it easy to extend the official stylesheets with specific processing.

# Easy to Learn

If you already know and use DocBook, DocBook Slides is for you:

- You can use the usual inline and block elements when marking up your text, you only have to learn a few new markup elements.

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

# Development Status

- DocBook Slides - just like DocBook - is an open source product and it is under constant development and improvement.

- The curently supported output formats are plain XHTML, S5 XHTML , W3C HTML Slidy and XSL FO . In the future, support for other important output formats (e.g. HTML5, EPUB) may be added.

# Tutorial Examples

Let's see some basic examples.

# A Minimal Markup 1

    <?xml version='1.0'?>
    <dbs:slides xmlns="http://docbook.org/ns/docbook"
      xmlns:dbs="http://docbook.org/ns/docbook-slides">
      <title>Presentation Title</title>

The root element with proper namespace declarations.

It contains the title but can have more.

# A Minimal Markup 2

      <dbs:foil>
        <title>Foil Title</title>
        <para>Foil content</para>
      </dbs:foil>
    </dbs:slides>

At least one foil obligatory.

A foil can contain any block element from DocBook.

# The Whole Example

Let's see the whole markup together:

    <?xml version='1.0'?>
    <dbs:slides xmlns="http://docbook.org/ns/docbook"
      xmlns:dbs="http://docbook.org/ns/docbook-slides">
      <title>Presentation Title</title>
      <dbs:foil>
        <title>Foil Title</title>
        <para>Foil content</para>
      </dbs:foil>
    </dbs:slides>

# Grouping Foils

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.

    <dbs:foilgroup>
      <title>Group 1</title>

      <para>This is an introduction.</para>

      <dbs:foil>
      ...
      </dbs:foil>
    </dbs:foilgroup>

# Markup Examples

Let's see how to create the particular foils with DocBook Slides.

# Info Content

You can wrap the title into the `<info>` element that comes from the DocBook schema. It also means you can add the usual authoring information here:

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

# Block Content

- You have access to all of the block content elements in DocBook, e.g. you can create a simple paragraph with `<para>`, just like in DocBook.

- Or you can use lists, like `<itemizedlist>`.

    Or <programlisting> with some code or markup inside.

# Inline Content

- Just like block elements, you can also use inline DocBook elements to mark up your content on your foils.

- For example, you can emphasize something with `<emphasis>` or you can mark `literal` text as such with `<literal>`.

- By the way, the inline markup citation above is marked up with `<tag>`.

- Apart from these, feel free to use the rest of the markup elements.

# FAQ Listings

What else can I use to make my slides useful and practical?

You can include some questions and answers with `<qandaset>` and related elements to answer some frequently asked questions.

# References

- Sometimes you need to add some remarks and some references to your slide content.

- For small remarks, you can use the `<footnote>` element to insert a footnote that will appear on the same foil where it is inserted.

- Or for references to external content - books and websites - you can include one or more bibliography foils in the end.

- On these foils, instead of the usual bulleted points, use the `<bibliography>` element and you will get a nicely formatted reference list.

- Use `<xref>` in the content to generate a link to the reference entry.

# Incremental Slides

- If you set the `dbs:incremental` attribute ...

- ... to `1` on a foil, ...

- ... then you will get incremental lists, ...

- ... like this if they are supported in the output format. (XHTML-based)

# Collapsible Lists

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

1. 1. If you set the `dbs:collapsible` attribute ...

   2. ... to `1` on a foil, ...

   3. ... then you will get collapsible lists, ...

   4. ... like this if they are supported in the output format. (Slidy)

# Building Blocks

- Slides are layout-oriented documents; formatting is a crucial part of them.

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

- You can use the `<dbs:block>` element that will be transformed to a container type in the generated document (e.g. `<div>` in HTML).

- You can also apply the `dbs:style` attribute to blocks and you can even embed them into each other.

- Use CSS or extend the XSLT stylesheets to control renering of your custom blocks.

# Block Example

This is the left block.

This is the right block. And it is marked incremental.

# Images and Formulas

# Incremental Images

This is only supported in XHTML-based output.

# Embedded SVG

You can embed SVG See `http://www.w3.org/TR/SVG11/`. code, like this:

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

# Embedded MathML

You can embed MathML See `http://www.w3.org/TR/MathML3/`. code, like this:

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

1
0
0
1

# Presentation

# Available Formats

Stylesheet | Description.
--- | ---
xhtml/plain.xsl | Single plain XHTML file.
xhtml/slidy.xsl | Single XHTL file in W3C HTML Slidy format.
xhtml/s5.xsl | Single XHTML file in S5 format.
fo/plain.xsl | XSL Formatting Objects for printed output.

# Plain XHTML

- It is a simple plain XHTML output with some classes given on the elements. These let you create your own CSS stylesheet for the rendering.

- It is actually quite similar to the S5 format with S5-specific parts removed. The objective with this format was simplicity and S5 already achieves that quite well but in case you do not want to use that framework, you can create your own one.

- The stylesheet to choose for this format is `xhtml/plain.xsl`.

# W3C HTML Slidy

- W3C `HTML Slidy` is an XHTML framework for presentations.

- It seems mature and well maintained.

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

- For HTML Slidy, use `xhtml/slidy.xsl`.

# S5 Format

- S5 stands for Simple Standards-Based Slide Show System.

- It is yet another XHTML-based framework for slideshows, like HTML Slidy.

- Its JavaScript code behaves somewhat differently and it is less mature.

- It supports incremental lists but in general, it is not so feature-rich as HTML Slidy.

- To create your S5 presentation, pick the `xhtml/s5.xsl` stylesheet.

# XSL FO Format

- XSL FO is an XML vocabulary to describe how formatted output is presented.

- It is used here as an intermediate format between DocBook Slides and printable output.

- First, generate the XSL FO document.

- Then use your XSL FO processor to render your printable document in PDF, PostScript, etc. depending on the capabilities of the software you use.

- If you need a free processor, take a look at Apache FOP .

# XSLT Parameters

- The provided stylesheets offer XSLT parameters to adjust some tunables of the output generation.

- The parameters are documented in the documentation that accompanies the DocBook XSL distribution.

- All the DocBook Slides stylesheets are extensions of the original DocBook stylesheets so adjusting their parameters may also affect your rendered slides.

# Customizations

Sometimes parameters are not enough and you need to modify the templates to achieve your goal. Customizations are easy to create with XSLT.

1. Just pick up a stylesheet that you want to customize.

2. Create a new, empty stylesheet that imports the original one.

3. Override the original templates that do not work in the way you desire.

4. Of course, this requires some knowledge in XSLT and you will need to read the code to see what to override.

# Authoring with DocBook Slides 5.0

# Choosing a Validator

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

- The DocBook Slides schema is described in the RELAX-NG grammar language.

- The recommended RELAX-NG validator is jing .

- Alternatively, you can use Emacs/nXML with the supplied `locatingrules.xml` file.

The RELAX-NG validation in the xmllint program from libxml2 is known to have bugs and does not work correctly with DocBook Slides.

# Validating Slides

- With `jing`, run: `jing ~/docbook-slides/slides.rng foo.xml`.

- For Emacs/nXML, you can put the following into your `emacs.conf`:

            (setq rng-schema-locating-files
              (append
                '("~/docbook-slides/locatingrules.xml")))

  Or you can do `M-x customize-variable rng-schema-locating-files` and then add the absolute path to the file.

# Transforming DocBook Slides Documents

- You need an XSLT processor to transform the documents. For example, you can use either `xsltproc` from libxslt , Xalan or Saxon.

- It is recommended to use `xsltproc`, since it is significantly faster than the other two and the DocBook Slides stylesheets were also tested with it.

- Pick the proper stylesheet for your chosen output format. For example, it is `xhtml/slidy.xsl` for HTML Slidy.

- Type: `xsltproc xsl/slides/xhtml/slidy.xsl foo.xml > foo.html`

# Rendering Printable Output

- First create the XSL FO document with XSLT: `xsltproc xsl/slides/fo/plain.xsl foo.xml > foo.fo`

- Then use your XSL FO processor to render the final document.

- For example, to render a PDF with Apache FOP, type: `fop foo.fo foo.pdf`

# DocBook Slides Limitations

# Foil Content

Creating slides is quite different from creating papers and books.

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

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

# Animations and Sound Effects

DocBook was invented for mostly printed or web content, while slides are rarely presented in a printed form.

- Slides are usually shown on computer screen or projector and may heavily use animated or audio content to support the presentations.

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

- Maybe a future HTML5 or OpenDocument support can bring in some new features but for now, you cannot really use animations and sound.

# Frequently Asked Questions

# Compatibility

Is DocBook Slides 5.0 stylesheets compatible with older versions of DocBook Slides or vice versa?

Not at all, since it is heavily redesigned. But you can find an XSLT transformation in the `tools/` directory, which can convert your slides to the new schema.

# Contribution

Can I contribute to the schema or to the stylesheets?

Of course, any contribution that can be useful for other users and fits the concept of DocBook Slides is more than welcome.

What to do with my contribution?

Please first ask review on the docbook-apps mailing list and users and other developers will tell you what to improve and how to submit your work for inclusion.

# Help

How can I get help in using the schema and the accompanying stylesheets?

There is a docbook-apps mailing list 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.

# Mini-Reference

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.

# dbs:slides

- May contain: db:title, db:titleabbrev, db:subtitle, db:info, dbs:foilgroup, dbs:foil

- Usage: It is the root element that encloses the authoring info and the particular foils that may be grouped to foil groups.

# dbs:foilgroup

- May contain: db:title, db:titleabbev, db:subtitle, db:info, [block content], dbs:foil, dbs:speakernotes, dbs:handoutnotes

- Usage: 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.

# dbs:foil

- May contain: db:title, db:titleabbev, db:subtitle, db:info, [block content], dbs:speakernotes, dbs:handoutnotes

- Usage: 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.

# dbs:block

- May contain: [block content]

- Usage: It divides the content into layout units that can later processed in a specific way.

# dbs:speakernotes

- May contain: [block content]

- Usage: Notes that are not meant to be presented to the audience but to the speaker.

# dbs:handoutnotes

- May contain: [block content]

- Usage: Notes that are not to accompany printed slides.

# Attribute dbs:incremental

- Usage: 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.

# Attribute dbs:collapsible

- Usage: 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.

# Attribute dbs:style

- Usage: 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 `class` attribute.

# Related Standards

# Related Standards

## Extensible Markup Language (XML)

W3C
http://www.w3.org/TR/REC-xml/

## The DocBook Schema Version 5.0

OASIS
http://docs.oasis-open.org/docbook/specs/docbook-5.0-spec-os.html

## XSL Transformations (XSLT) Version 1.0

W3C
http://www.w3.org/TR/xslt

## Extensible Stylesheet Language (XSL) Version 1.1

W3C
http://www.w3.org/TR/xsl/

# Supported HTML Presentation Frameworks

# Supported HTML Presentation Frameworks

## S5

A Simple Standards-Based Slide Show System
http://meyerweb.com/eric/tools/s5/

## HTML Slidy

Slide Shows in HTML and XHTML
www.w3.org/Talks/Tools/Slidy2/

# Recommended Tools

# Recommended Tools

## Jing RELAX-NG validator

http://www.thaiopensource.com/relaxng/jing.html

## libxslt

The XSLT C library for GNOME
http://xmlsoft.org/xslt/

## Apache FOP

http://xmlgraphics.apache.org/fop/