In the rabbit hole

Generate slides from DocBook

Introduction

I’m a big fan of LaTeX. However, when it comes to details, LaTeX is not what it sells you: you can’t really separate the content from the display when you need something nicer than the default. Moreover, the semantic description of parts of the content in LaTeX can be improved. But why? DocBook do the job, right?

Yes, DocBook seems to do a big part of the job. However, it is still difficult to produce documents from DocBook (FOP… seriously, you don’t want to use that, it’s heavy). You can still produce HTML/XHTML documents but for reports, you may want PDF. However, for slides, with a bit of CSS and JavaScript, it start to be interesting. Let’s do something like that!

In this article, we will parse a simple slide (with the DocBook and DocBook Slides formats) on a Linux, thanks to the xsltproc (part of the XSLT project of Gnome).

Get the DocBook stylesheets

To generate slides from DocBook format, you first need to get the stylesheets from the official forge docbook.sourceforge.net. You can download latest snapshots from snapshots menu or directly from snapshots.docbook.org.

Download the ns version (and the doc if you want) then unzip it somewhere. We’ll find everything we need for slides into docbook-xsl-ns-snapshot/slides/ directory.

How it works?

First you need to create your DocBook file (XML format). For slides, an extension is provided with another namespace which allow you to add a few more things related to a slides. It is called DocBook Slides and the namespace is http://docbook.org/ns/docbook-slides. Once your document is created, you need to parse it with an XSL stylesheet to produce your HTML/XHTML file. Then, there is a few other details to make it work.

Create the document

First of all, this is simple DocBook file. you can use either the DocBook roots or the specific root from DocBook Slides extension to begin your document. We will use the extension’s root for the XML file.

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

Each slide will be enclosed in a <dbs:foil> element. For each <dbs:foil> element, you can add <title> then content (you can add a lot of things but we will make it simple for now).

Let’s try a simple slide with 3 slides with the file docbook-slide-example.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">
	<title>Create DocBook slides</title>
	<dbs:foil>
		<title>Introduction</title>
		<para>This is very simple, you'll see</para>
	</dbs:foil>
	<dbs:foil dbs:incremental="1">
		<title>Create itemized list</title>
		<itemizedlist>
			<listitem>
				<para>For help...</para>
			</listitem>
			<listitem>
				<para>... you can refer to...</para>
			</listitem>
			<listitem>
				<para>
					... the official website
					<link
						xlink:href="http://www.docbook.org/">
						DocBook
					</link>
				</para>
			</listitem>
		</itemizedlist>
	</dbs:foil>
	<dbs:foil>
		<title>Display source code</title>
		<para>Every XML file should start with the following line</para>
		<programlisting>
			&lt;?xml version='1.0'?&gt;
		</programlisting>
	</dbs:foil>
</dbs:slides>

Parse the document

Every stylesheet that you can use to generate slides are in docbook-xsl-ns-snapshot/slides/xhtml/. The one we are interested in to create fun presentation is slidy.xsl. The document you want to parse is docbook-slide-example.xml. To parse it, we will use xsltproc then redirect the output in our XHTML file.

	xsltproc \
		docbook-xsl-ns-snapshot/slides/xhtml/slidy.xsl \
		docbook-slide-example.xml > docbook-slide-example.xhtml

Now, you can display the file. However, you’ll see nothing spectacular since we do not furnish the CSS and JavaScript files.

A few more details

To complete the creation of our slides, we will need to copy the needed CSS and JavaScript files into the right directory. All of these files can be found into docbook-xsl-ns-snapshot/slides/slidy/. This slidy directory is expected to be found in a directory called files next to the XHTML file. Let’s copy the directory.

	mkdir files/
	cp -R docbook-xsl-ns-snapshot/slides/slidy/ files/slidy

In your directory, you should now see the following file structure.

	|
	|-- docbook-slide-example.xhtml
	|-- docbook-slide-example.xml
	|-- docbook-xsl-ns-snapshot
	|   |-- slides
	|   |   |-- ...
	|   |   +-- ...
	|   +-- ...
	+-- files
		+-- slidy
			|-- ...
			+-- ...

Reload the XHTML file in your browser, you should be able to see the nice slide template from the W3C!

References

docbook.sourceforge.net, the official forge of DocBook
snapshots.docbook.org, where you can download snapshots of DocBook stylesheets
In docbook-xsl-ns-snapshot/slides/doc/, the file slides.xml can be processed with xsltproc and slidy.xsl to produce a short documentation.

links

social