<?xml version='1.0'?>
<!-- $FreeBSD$ -->
<!DOCTYPE slides SYSTEM
"/usr/local/share/xsl/slides/schema/dtd/slides.dtd" [
<!ENTITY % freebsd SYSTEM "../../../share/xml/freebsd.ent">
%freebsd;
]>
<?dbhtml graphics-dir="/usr/local/share/xsl/slides/graphics" css-stylesheet-dir="/usr/local/share/xsl/slides/browser"?>
<?dbhtml script-dir="/usr/local/share/xsl/slides/browser"?>
<slides>
<!-- 1 -->
<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>
<!-- 2 -->
<foil id="intro-outline"><title>Outline</title>
<itemizedlist>
<listitem>Overview of FreeBSD Documentation Architecture</listitem>
<listitem>How does DocBook Slides fit in?</listitem>
<listitem>Why is it useful?</listitem>
<listitem>XSLT Tools</listitem>
<listitem>XSL-FO</listitem>
<listitem>Questions</listitem>
</itemizedlist>
</foil>
<!-- 3 -->
<foil id="docproj-overview"><title>Documentation Architecture</title>
<itemizedlist>
<listitem>Documentation Set:<itemizedlist>
<listitem>40 articles.</listitem>
<listitem>9 books.</listitem>
<listitem>Hundreds of man pages.</listitem>
<listitem>Available in a dozen languages.</listitem>
</itemizedlist></listitem>
<listitem>157 developers have made a commit to doc/ or www/ in last 12 months.</listitem>
<listitem>Books and articles authored in structured SGML/XML
DocBook DTD.</listitem>
<listitem>Robust makefile infrastructure allows one to build PDF,
HTML, or ASCII output with simple 'make' command.</listitem>
</itemizedlist>
</foil>
<!-- 4 -->
<foil id="docproj-docbook"><title>DocBook?</title>
<itemizedlist>
<listitem>Structured documentation format that allows one to
specify semantics of a document rather than the
presentation.</listitem>
<listitem>Stylesheets take care of details such as always printing
commands in a <literal>monospace</literal> font, etc.
Stylesheets can make different presentation decisions based on
the output format.</listitem>
<listitem>For example, HTML stylesheets may use a CSS mouseover on
acronyms so that the full technical term can be
displayed.</listitem>
<listitem>Links to online man pages can be automatically generated
for <literal><command></literal>s in HTML output.</listitem>
</itemizedlist>
</foil>
<!-- 5 -->
<foil id="docproj-sgml"><title>DocBook SGML/XML</title>
<itemizedlist>
<listitem>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.</listitem>
<listitem>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.</listitem>
<listitem>Since the content is structured, intelligent search
engines could differentiate between, say,
<literal>touch</literal>, the Unix Command, and
<emphasis>touch</emphasis>, the feeling. Search engines,
agents, and other information processing tools have information
about the meaning of the content.</listitem>
</itemizedlist>
</foil>
<!-- 6 -->
<foil id="docproj-toolchain"><title>Doc Project Toolchain</title>
<itemizedlist>
<listitem>Traditionally, we have used the Jade DSSSL Engine to
convert the DocBook SGML files into HTML, text, and PostScript
formats.</listitem>
<listitem>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.</listitem>
<listitem>For Print output, we use the TeX backend of Jade and
then rely on TeX to generate the PostScript output.</listitem>
<listitem>The makefiles handle all of this, so <command>make
FORMATS=html</command> or <command>make FORMATS=ps</command> is
all you really need to know about if you have all of the tools
installed.</listitem>
</itemizedlist>
</foil>
<!-- 7 -->
<foil id="docproj-jade"><title>Why Jade/DSSSL and not XSLT?</title>
<itemizedlist>
<listitem>The DSSSL stylesheet specification proved difficult to
implement in practice, and so Jade was the only widely
distributed implementation.</listitem>
<listitem>The XSLT language has been much more widely adopted, and
the goal is to eventually transition the FreeBSD Documentation
Set to XML/XSLT.</listitem>
<listitem>We already use XSLT extensively for the web site builds,
and it possible to build parts of the documentation set with
XSLT as well.</listitem>
<listitem>The new slides infrastructure relies solely on XSLT and
XSL-FO, without any DSSSL stylesheets.</listitem>
</itemizedlist>
</foil>
<!-- 8 -->
<foil id="what-is-docbook-slides"><title>What is DocBook Slides?</title>
<itemizedlist>
<listitem>A DTD based on Simplified DocBook XML Schema.</listitem>
<listitem>Provides a collection of tags useful for structuring
content into slides, lists, and paragraphs for
presentations.</listitem>
<listitem>Also provides tags for describing technical content such
as commands, variables, etc..</listitem>
<listitem>Stylesheets can create HTML or PDF output by default.</listitem>
<listitem>OpenOffice Impress output should also be possible.</listitem>
</itemizedlist>
</foil>
<!-- 9 -->
<foil id="example-slides-xml"><title>Example Slide : Preamble</title>
<para>The preamble:</para>
<programlisting scale="50%"><?xml version='1.0'?>
<!DOCTYPE slides SYSTEM
"/usr/.../schema/dtd/slides.dtd" [
<!ENTITY % freebsd SYSTEM
"../../../share/xml/freebsd.ent">
%freebsd;
]></programlisting>
<para>Note that the default <filename>freebsd.ent</filename> 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.</para>
</foil>
<!-- 10 -->
<foil id="example-slides-xml-2"><title>Example Slide : Title Page</title>
<programlisting><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></programlisting>
</foil>
<foil id="example-slides-xml-3"><title>Example Slide : Content</title>
<programlisting><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></programlisting></foil>
<foil id="tools-basics"><title>Tools - Basics</title>
<itemizedlist>
<listitem>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.</listitem>
<listitem>Additional options exist to use different XSLT or XSL-FO
processors, or to specify alternate stylesheets.</listitem>
<listitem><literal>FORMATS=openoffice</literal> support would be really
cool. Any takers?</listitem>
<listitem>All of the relevant software is installed with the
<filename>textproc/docproj</filename> port.</listitem>
</itemizedlist>
<screen>$ <userinput>make USE_XEP=1 FORMATS=pdf</userinput></screen>
</foil>
<foil id="tools-2"><title>Tools</title>
<para>An XSLT processor is required to transform the source XML
document for both HTML or PDF output. The Open Source
<literal>xsltproc</literal> processor is fastest and supports
the basics necessary for using the Slides DTD.</para>
<para>Other alternatives</para>
<itemizedlist>
<listitem>Saxon</listitem>
<listitem>XT (James Clark)</listitem>
<listitem>Xalan (Apache XML Project)</listitem>
<listitem>MSXSLT</listitem>
<listitem>See ports collection.</listitem>
</itemizedlist>
</foil>
<foil id="tools-html"><title>XSLT Basics</title>
<para>Used extensively in the <literal>www/</literal> tree, but for
various reasons we haven't fully migrated to building the FreeBSD
<literal>doc/</literal> tree with it.</para>
<para>Stylesheets can be layered to arbitrary depth. Templates at
layer N take precedence over those at level N-1.</para>
<programlisting><xsl:template match="command">
<tt><xsl:value-of select="."></tt>
</xsl:template></programlisting>
<para>Numerous examples in the <filename>doc/</filename> of layered
stylesheets built on top of default DocBook XSLT stylesheets.</para>
<!-- XXX
<para>FreeBSD customizations used by other open source projects and
commercial companies for producing output customizations for books,
etc.</para>-->
</foil>
<foil id="tools-html-2"><title>Tools for HTML output</title>
<para>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.</para>
<mediaobject filename="xml_1.png"/>
</foil>
<foil id="tools-html-benefits"><title>Benefits of HTML output</title>
<itemizedlist>
<listitem>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
<literal>http://www.FreeBSD.org</literal>.</listitem>
<listitem>More amenable to searching.</listitem>
<listitem>Recent presentations can be indexed together rather than
visiting different personal homepages or conference websites
looking for most recent FreeBSD presentations.</listitem>
<listitem>Text formats easier for translation teams to work
with.</listitem>
<listitem>Easier for documentation teams to find relevant
information from HTML slides and incorporate them into the
Handbook and other FreeBSD documentation sources.</listitem>
</itemizedlist>
</foil>
<foil id="tools-xslfo"><title>XSL-FO</title>
<itemizedlist>
<listitem>For print output, the XSLT processor transforms the XML document
into an intermediate XSL-FO document.</listitem>
<listitem>XSL-FO is an XML format that contains detailed
presentation information about the content.</listitem>
<listitem>There are many open source and commercial XSL-FO
processors.
<itemizedlist>
<listitem>FOP (Apache XML Project)</listitem>
<listitem>RenderX XEP (commercial)</listitem>
<listitem>PassiveTeX</listitem>
</itemizedlist></listitem></itemizedlist>
<imageobject filename="xml_2.png"/>
<para>What does <filename>file.fo</filename> look like?</para>
</foil>
<foil id="tools-xslfo-ex"><title>XSL-FO Example</title>
<para>XSL-FO files not really meant for hand-generation, but you asked
for it :</para>
<programlisting><?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></programlisting>
<para>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.</para>
</foil>
<foil id="tools-xslfo-ex2"><title>XSL-FO Example Part 2</title>
<programlisting> <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></programlisting>
<itemizedlist>
<listitem>Pages in the document are grouped into sequences; each sequence
starts from a new page.</listitem>
<listitem>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.</listitem>
<listitem><literal>fo:block</literal> objects roughly correspond to
<literal><DIV></literal> in HTML, and normally include a paragraph
of text.</listitem>
</itemizedlist>
</foil>
<foil id="tools-xslfo-passivetex"><title>XSL-FO Tools - PassiveTeX</title>
<para>An open source implementation based on TeX similar to the
JadeTeX macro package used for creating print output from DSSSL
stylesheets.</para>
<para>Pros:</para>
<itemizedlist>
<listitem>Open source.</listitem>
</itemizedlist>
<para>Cons:</para>
<itemizedlist>
<listitem>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).</listitem>
<listitem>Requires a full TeX installation rather than generating
PDF directly. Difficult to debug.</listitem>
</itemizedlist></foil>
<foil id="tools-xslfo-fop"><title>XSL-FO Tools - FOP</title>
<para>Open source implementation in Java from the Apache
Project.</para>
<para>Pros:</para>
<itemizedlist>
<listitem>Open source.</listitem>
<listitem>Handles some implementation features that PassiveTeX does not.</listitem>
</itemizedlist>
<para>Cons:</para>
<itemizedlist>
<listitem>Not as conformant as the commercial processors. Many
features are missing.</listitem>
<listitem>A Work in Progress.</listitem>
</itemizedlist></foil>
<foil id="future-work"><title>Future Work</title>
<itemizedlist>
<listitem>This presentation will be committed to CVS later today
so that it appears on the FreeBSD web site as an
example.</listitem>
<listitem>Implement OpenOffice Impress output format.</listitem>
<listitem>Make better use of XML Documentation sources such as
release notes to create more dynamic slides.</listitem>
<listitem>Add more stylesheet options for PDF output.</listitem>
<listitem>Find/write better open source XSL-FO toolchain. </listitem>
</itemizedlist>
</foil>
<foil id="more-information"><title>More Information</title>
<itemizedlist>
<listitem><ulink
url="http://sourceforge.net/projects/docbook/">DocBook SourceForge
Project Page</ulink></listitem>
<listitem><filename>doc/share/mk/doc.slides.mk</filename></listitem>
<listitem><literal>docbook-apps@</literal> mailing
list.</listitem>
<listitem><literal>freebsd-doc@</literal> mailing list.</listitem>
<listitem>This example presentation.</listitem>
<listitem>If all else fails, send me an email and I'd be happy to
help you design a presentation in DocBook Slides.</listitem>
</itemizedlist>
</foil>
</slides>