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>