Add slides from BSDCan 2005 about the DocBook Slides infrastructure.
This commit is contained in:
Murray Stokely
parent
0ad41f2e3f
commit
77875e69ad
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=24574
2 changed files with 489 additions and 0 deletions
22
en_US.ISO8859-1/slides/20050513-bsdcan-slides/Makefile
Normal file
22
en_US.ISO8859-1/slides/20050513-bsdcan-slides/Makefile
Normal file
|
|
@ -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"
|
||||
467
en_US.ISO8859-1/slides/20050513-bsdcan-slides/slides.xml
Normal file
467
en_US.ISO8859-1/slides/20050513-bsdcan-slides/slides.xml
Normal file
|
|
@ -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><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>
|
||||
Loading…
Reference in a new issue