DocBook Slides Gábor Kövesdán The DocBook Project gabor@kovesdan.org 3 Aug 2012 5.0 2012 Gábor Kövesdán DocBook Slides ... is a multi-namespace schema extension to the original DocBook schema. was originally created by NormanWalsh. and was later redesigned for DocBook 5.0 by GáborKö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. 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. Let's see some features of DocBook Slides. 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. 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. 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. Let's see some basic examples. <?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. <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. 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> 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. This is an introduction. ... ]]> Let's see how to create the particular foils with DocBook Slides. 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: John Doe FooBar Inc. 2012 ]]> 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. 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. 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. 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. 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) You can see a collapsible list below (depending on the output format). Click on the node to expand it. If you set the dbs:collapsible attribute ... ... to 1 on a foil, ... ... then you will get collapsible lists, ... ... like this if they are supported in the output format. (Slidy) 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. This is the left block. This is the right block. And it is marked incremental. This is only supported in XHTML-based output. You can embed SVG See http://www.w3.org/TR/SVG11/. code, like this: ]]> You can embed MathML See http://www.w3.org/TR/MathML3/. code, like this: 10 01 ]]> $\begin{pmatrix}1 & 0\\ 0 & 1\end{pmatrix}$ StylesheetDescription. 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. 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 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 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 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 . 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. Sometimes parameters are not enough and you need to modify the templates to achieve your goal. Customizations are easy to create with XSLT. Just pick up a stylesheet that you want to customize. Create a new, empty stylesheet that imports the original one. Override the original templates that do not work in the way you desire. Of course, this requires some knowledge in XSLT and you will need to read the code to see what to override. 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. 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. 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 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 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. 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. 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. 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. 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. 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. 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. 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. 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. May contain: [block content] Usage: It divides the content into layout units that can later processed in a specific way. May contain: [block content] Usage: Notes that are not meant to be presented to the audience but to the speaker. May contain: [block content] Usage: Notes that are not to accompany printed slides. 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. 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. 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. W3C http://www.w3.org/TR/REC-xml/ OASIS http://docs.oasis-open.org/docbook/specs/docbook-5.0-spec-os.html W3C http://www.w3.org/TR/xslt W3C http://www.w3.org/TR/xsl/ A Simple Standards-Based Slide Show System http://meyerweb.com/eric/tools/s5/ Slide Shows in HTML and XHTML www.w3.org/Talks/Tools/Slidy2/ http://www.thaiopensource.com/relaxng/jing.html The XSLT C library for GNOME http://xmlsoft.org/xslt/ http://xmlgraphics.apache.org/fop/