467 lines
15 KiB
XML
467 lines
15 KiB
XML
<?xml version='1.0'?>
|
|
|
|
<!-- $FreeBSD$ -->
|
|
|
|
<!DOCTYPE slides SYSTEM
|
|
"/usr/local/share/xsl/slides/schema/dtd/slides.dtd" [
|
|
<!ENTITY % freebsd SYSTEM "../../../share/sgml/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/sgml/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>
|