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