%freebsd; ]> DocBook Slides MurrayStokely 13 May 2005 2005 FreeBSD Mall, Inc. Overview of FreeBSD Documentation Architecture How does DocBook Slides fit in? Why is it useful? XSLT Tools XSL-FO Questions Documentation Set: 40 articles. 9 books. Hundreds of man pages. Available in a dozen languages. 157 developers have made a commit to doc/ or www/ in last 12 months. Books and articles authored in structured SGML/XML DocBook DTD. Robust makefile infrastructure allows one to build PDF, HTML, or ASCII output with simple 'make' command. Structured documentation format that allows one to specify semantics of a document rather than the presentation. Stylesheets take care of details such as always printing commands in a monospace font, etc. Stylesheets can make different presentation decisions based on the output format. For example, HTML stylesheets may use a CSS mouseover on acronyms so that the full technical term can be displayed. Links to online man pages can be automatically generated for <command>s in HTML output. DocBook is available as both an SGML DTD and as an XML Schema. For various reasons, most of our documentation is in SGML format, but can easily be converted to XML for processing with XML tools. Both SGML and XML allow include files, so we can share content across the release notes, all 40 articles, and 9 books in the documentation set. Since the content is structured, intelligent search engines could differentiate between, say, touch, the Unix Command, and touch, the feeling. Search engines, agents, and other information processing tools have information about the meaning of the content. Traditionally, we have used the Jade DSSSL Engine to convert the DocBook SGML files into HTML, text, and PostScript formats. Jade can output HTML directly with the help of the DSSSL stylesheets and extensive FreeBSD customizations. The text formats can then be converted from the HTML with the help of a text based web browser. For Print output, we use the TeX backend of Jade and then rely on TeX to generate the PostScript output. The makefiles handle all of this, so make FORMATS=html or make FORMATS=ps is all you really need to know about if you have all of the tools installed. The DSSSL stylesheet specification proved difficult to implement in practice, and so Jade was the only widely distributed implementation. The XSLT language has been much more widely adopted, and the goal is to eventually transition the FreeBSD Documentation Set to XML/XSLT. We already use XSLT extensively for the web site builds, and it possible to build parts of the documentation set with XSLT as well. The new slides infrastructure relies solely on XSLT and XSL-FO, without any DSSSL stylesheets. A DTD based on Simplified DocBook XML Schema. Provides a collection of tags useful for structuring content into slides, lists, and paragraphs for presentations. Also provides tags for describing technical content such as commands, variables, etc.. Stylesheets can create HTML or PDF output by default. OpenOffice Impress output should also be possible. The preamble: <?xml version='1.0'?> <!DOCTYPE slides SYSTEM "/usr/.../schema/dtd/slides.dtd" [ <!ENTITY % freebsd SYSTEM "../../../share/xml/freebsd.ent"> %freebsd; ]> Note that the default freebsd.ent file from the FreeBSD Documentation Project is brought in. This provides entities to represent the newest release of FreeBSD, the number of ports in the Ports Collection, etc. <slides> <slidesinfo> <title>DocBook Slides, XSLT, and XSL-FO</title> <titleabbrev>DocBook Slides</titleabbrev> <author> <firstname>Murray</firstname> <surname>Stokely</surname> </author> <pubdate>13 May 2005</pubdate> <copyright> <year>2005</year> <holder>FreeBSD Mall, Inc.</holder> </copyright> </slidesinfo> <foil><title>My Title</title> <para>Creating slides is easy.</para> <itemizedlist> <listitem>Point 1.</listitem> <listitem>Point 2.</listitem> <listitem>Point 3.</listitem> <listitem>Point 4.</listitem> </itemizedlist> <para> There are &os.num; ports in &rel.current;. </para> </foil> As with other SGML/XML document types in the tree, DocBook slides are supported by a robust Makefile infrastructure to allow the building of HTML or PDF output. Additional options exist to use different XSLT or XSL-FO processors, or to specify alternate stylesheets. FORMATS=openoffice support would be really cool. Any takers? All of the relevant software is installed with the textproc/docproj port. $ make USE_XEP=1 FORMATS=pdf An XSLT processor is required to transform the source XML document for both HTML or PDF output. The Open Source xsltproc processor is fastest and supports the basics necessary for using the Slides DTD. Other alternatives Saxon XT (James Clark) Xalan (Apache XML Project) MSXSLT See ports collection. Used extensively in the www/ tree, but for various reasons we haven't fully migrated to building the FreeBSD doc/ tree with it. Stylesheets can be layered to arbitrary depth. Templates at layer N take precedence over those at level N-1. <xsl:template match="command"> <tt><xsl:value-of select="."></tt> </xsl:template> Numerous examples in the doc/ of layered stylesheets built on top of default DocBook XSLT stylesheets. The default XSL stylesheets for HTML output use chunking to generate one HTML page per foil with navigation icons to allow easy hypertext browsing of presentations. Great for advocacy: Allows the FreeBSD Project to get "more mileage" out of presentations by providing a space to archive them in HTML form on http://www.FreeBSD.org. More amenable to searching. Recent presentations can be indexed together rather than visiting different personal homepages or conference websites looking for most recent FreeBSD presentations. Text formats easier for translation teams to work with. Easier for documentation teams to find relevant information from HTML slides and incorporate them into the Handbook and other FreeBSD documentation sources. For print output, the XSLT processor transforms the XML document into an intermediate XSL-FO document. XSL-FO is an XML format that contains detailed presentation information about the content. There are many open source and commercial XSL-FO processors. FOP (Apache XML Project) RenderX XEP (commercial) PassiveTeX What does file.fo look like? XSL-FO files not really meant for hand-generation, but you asked for it : <?xml version="1.0" encoding="iso-8859-1"?> <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format"> <fo:layout-master-set> <fo:simple-page-master master-name="my-page"> <fo:region-body margin="1in"/> </fo:simple-page-master> </fo:layout-master-set> The layout-master-set contains one or more declarations of page masters and page sequence masters elements that define layouts of single pages and page sequences. In the example, the area should have a 1 inch margin from all sides of the page. <fo:page-sequence master-reference="my-page"> <fo:flow flow-name="xsl-region-body"> <fo:block>Hello, world!</fo:block> </fo:flow> </fo:page-sequence> </fo:root> Pages in the document are grouped into sequences; each sequence starts from a new page. Flow is the container object for all user text in the document. Everything contained in the flow will be formatted into regions on pages generated inside the page sequence. fo:block objects roughly correspond to <DIV> in HTML, and normally include a paragraph of text. An open source implementation based on TeX similar to the JadeTeX macro package used for creating print output from DSSSL stylesheets. Pros: Open source. Cons: Does not implement many features of XSL-FO that are difficult to implement in TeX, such as background images. (The daemon in the background of this slide would be impossible to produce with PassiveTeX). Requires a full TeX installation rather than generating PDF directly. Difficult to debug. Open source implementation in Java from the Apache Project. Pros: Open source. Handles some implementation features that PassiveTeX does not. Cons: Not as conformant as the commercial processors. Many features are missing. A Work in Progress. This presentation will be committed to CVS later today so that it appears on the FreeBSD web site as an example. Implement OpenOffice Impress output format. Make better use of XML Documentation sources such as release notes to create more dynamic slides. Add more stylesheet options for PDF output. Find/write better open source XSL-FO toolchain. DocBook SourceForge Project Page doc/share/mk/doc.slides.mk docbook-apps@ mailing list. freebsd-doc@ mailing list. This example presentation. If all else fails, send me an email and I'd be happy to help you design a presentation in DocBook Slides.