aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/slides/20050513-bsdcan-slides
diff options
context:
space:
mode:
authorMurray Stokely <murray@FreeBSD.org>2005-05-13 19:48:41 +0000
committerMurray Stokely <murray@FreeBSD.org>2005-05-13 19:48:41 +0000
commit77875e69ad82ad23041b63cda7b951abaeea8c78 (patch)
tree96aeb5d769fa813fcd8ea88b58388665834577f0 /en_US.ISO8859-1/slides/20050513-bsdcan-slides
parent0ad41f2e3f96e02bec08f63b80bbe1d8cc4d7d6d (diff)
downloaddoc-77875e69ad82ad23041b63cda7b951abaeea8c78.tar.gz
doc-77875e69ad82ad23041b63cda7b951abaeea8c78.zip
Add slides from BSDCan 2005 about the DocBook Slides infrastructure.
Notes
Notes: svn path=/head/; revision=24574
Diffstat (limited to 'en_US.ISO8859-1/slides/20050513-bsdcan-slides')
-rw-r--r--en_US.ISO8859-1/slides/20050513-bsdcan-slides/Makefile22
-rw-r--r--en_US.ISO8859-1/slides/20050513-bsdcan-slides/slides.xml467
2 files changed, 489 insertions, 0 deletions
diff --git a/en_US.ISO8859-1/slides/20050513-bsdcan-slides/Makefile b/en_US.ISO8859-1/slides/20050513-bsdcan-slides/Makefile
new file mode 100644
index 0000000000..44ec75d1c4
--- /dev/null
+++ b/en_US.ISO8859-1/slides/20050513-bsdcan-slides/Makefile
@@ -0,0 +1,22 @@
+#
+# $FreeBSD$
+#
+# Presentation for BSDCan 2005 about DocBook Slides Infrastructure
+#
+
+DOCFORMAT= slides
+DOC= slides
+
+FORMATS?= html
+
+SRCS= slides.xml
+
+#EPS2PNM_RES= 200
+#LOCAL_IMAGES_EN= xml_1.eps
+#LOCAL_IMAGES_EN+= xml_2.eps
+
+XSLTPROCFLAGS= --nonet --xinclude --stringparam draft.mode no
+XSLTPROCOPTS= ${XSLTPROCFLAGS}
+
+DOC_PREFIX?= ${.CURDIR}/../../..
+.include "${DOC_PREFIX}/share/mk/doc.project.mk"
diff --git a/en_US.ISO8859-1/slides/20050513-bsdcan-slides/slides.xml b/en_US.ISO8859-1/slides/20050513-bsdcan-slides/slides.xml
new file mode 100644
index 0000000000..a33d07ebcb
--- /dev/null
+++ b/en_US.ISO8859-1/slides/20050513-bsdcan-slides/slides.xml
@@ -0,0 +1,467 @@
+<?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>&lt;command&gt;</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%">&lt;?xml version='1.0'?>
+&lt;!DOCTYPE slides SYSTEM
+"/usr/.../schema/dtd/slides.dtd" [
+&lt;!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>&lt;slides>
+&lt;slidesinfo>
+ &lt;title>DocBook Slides, XSLT, and XSL-FO&lt;/title>
+ &lt;titleabbrev>DocBook Slides&lt;/titleabbrev>
+
+ &lt;author>
+ &lt;firstname>Murray&lt;/firstname>
+ &lt;surname>Stokely&lt;/surname>
+ &lt;/author>
+ &lt;pubdate>13 May 2005&lt;/pubdate>
+ &lt;copyright>
+ &lt;year>2005&lt;/year>
+ &lt;holder>FreeBSD Mall, Inc.&lt;/holder>
+ &lt;/copyright>
+&lt;/slidesinfo></programlisting>
+</foil>
+
+<foil id="example-slides-xml-3"><title>Example Slide : Content</title>
+<programlisting>&lt;foil>&lt;title>My Title&lt;/title>
+
+ &lt;para>Creating slides is easy.&lt;/para>
+
+ &lt;itemizedlist>
+ &lt;listitem>Point 1.&lt;/listitem>
+ &lt;listitem>Point 2.&lt;/listitem>
+ &lt;listitem>Point 3.&lt;/listitem>
+ &lt;listitem>Point 4.&lt;/listitem>
+ &lt;/itemizedlist>
+
+ &lt;para>
+ There are &amp;os.num; ports in &amp;rel.current;.
+ &lt;/para>
+&lt;/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>&lt;xsl:template match="command">
+ &lt;tt>&lt;xsl:value-of select=".">&lt;/tt>
+&lt;/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>&lt;?xml version="1.0" encoding="iso-8859-1"?>
+&lt;fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
+ &lt;fo:layout-master-set>
+ &lt;fo:simple-page-master master-name="my-page">
+ &lt;fo:region-body margin="1in"/>
+ &lt;/fo:simple-page-master>
+ &lt;/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> &lt;fo:page-sequence master-reference="my-page">
+ &lt;fo:flow flow-name="xsl-region-body">
+ &lt;fo:block>Hello, world!&lt;/fo:block>
+ &lt;/fo:flow>
+ &lt;/fo:page-sequence>
+&lt;/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>&lt;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>