Toward Single-Source Publishing Using DocBook XML Dan York Director of Training Mitel Networks Corporation Network Server Solutions Group (formerly e-smith, inc.) November 8, 2001 XML Users Group of Ottawa Ottawa, Ontario, Canada 2001 Dan York Introduction Examples Stylesheets Tools Extensions Resources

Documentation staff have always been seeking a system that... Uses a single source file that can be exported into multiple output formats Allows the easy automation of production Allows for the easy customization of formatting A system for writing structured documents using SGML or XML Targeted at documents about computer technology, but can be used for other subjects Also other uses such as web sites and slides (like these!) Supported by a growing number of commercial and free software/open source tools Supported by a large community of DocBook users and developers Created around 1991 originally by HaL Computer Systems and O'Reilly & Associates Later developed by a wide range of companies including: Novell Digital Equipment Corporation Hewlett Packard Sun Microsystems SCO Also Fujitsu, Hitachi, Unisys and many others Now maintained by OASIS Beyond the companies mentioned previously, DocBook is widely used within the free software/open source community, including by the following organizations and companies: Linux Documentation Project FreeBSD Documentation Project GNOME Documentation Project KDE Documentation Project Caldera Systems Mandrakesoft Red Hat SuSE Strong user/developer community Easily customizable and extensible "standard" stylesheets Open source and commercial tools available Output to multiple formats, including: HTML HTML Help Java Help man pages (UNIX/Linux manual pages) MIF (FrameMaker) PDF PostScript RTF (Microsoft) TeX Texinfo pages XHTML XSL Formatting Objects (FO) Number of elements can be intimidating. Learning curve for newcomers not used to tagged languages can be intimidating. Setting up some of the open source tools can be intimidating. Some of the open source tools do not provide the desired level of control or maturity. (ex. XML PDF generation)

This is a paragraph. ... ... ... ... ... ... ]]> This is an introductory paragraph. This is a paragraph. Blah, blah, blah... ... ... ... ... ... ]]> DocBook contains sections that can be nested. Either of two styles, specific (<sect1-5>): ... ... ... ... ... ... ...]]> Generic (nested <section> tags):

...

...

...

...

...

...

...

]]> No theoretical limit on depth of nesting. Provides a bulleted list and maps to a ]]> in HTML. Item A Item B Item C ]]> Provides a numbered list and maps to a ]]> in HTML. Item A Item B Item C ]]> Provides a list of terms and definitions. Maps to a ]]> in HTML. ]]> An image is usually part of a larger ]]> tag. The simple form is: ]]> A more complex form allows for multiple image formats and also alternative text: Our company logo ]]> Tables can be created in DocBook: ]]> Also an ]]> tag for tables that do not need a title. Additionally, informal tables will not appear in a generated list of tables. ]]> and ]]> tag are included and will be numbered and have titles. ]]> and ]]> will not be numbered. Examples: print "Hello, world!" ]]> Several forms of "admonitions" are available. "Note": This is a note]]> This is a note "Warning": This is a warning]]> This is a warning "Tip": This is a tip]]> This is a tip "Caution": This is a caution]]> This is a caution "Important": This is important]]> This is important This is some text.]]> This is some bold text.]]> ]]> ]]> Many others ]]> ]]> ]]> Can use <![CDATA[]]> to include XML/HTML code, as in: <![CDATA[This is a list item.]]>]]> Based on id's found in other elements Docbook page]]> Internal link]]> ]]> Example: ... See the intro section for more info. ]]> Allows creation of indices. ]]> takes a primary and secondary terms Example: xsltprocXSLT processing, which is part of "libxslt".]]> It is also possible to create glossaries and bibliographies ]]> ]]> ]]> Many, many, many others... http://www.docbook.org/tdg/en/html/ref-elements.html DocBook can also be used for question and answer sets: What is the answer to the ultimate question? 42 What kind of stylesheets are available? XSLT or DSSSL ]]> Can be used for items such as Linux/UNIX man pages. Example: ls 1 ls (options)... (file)... List information about the files... ]]>

"Standard" set of "modular" stylesheets maintained primarily by Norman Walsh. Two sets of stylesheets: XSL DSSSL Available from http://docbook.sourceforge.net/ XSLT stylesheets can transform DocBook XML into the following formats: HTML HTML Help (for Windows Help) Java Help XHTML XSL Formatting Objects (FO) Other tools can take FO into PDF, PostScript, etc. DSSSL stylesheets can transform DocBook SGML into the following formats: HTML MIF RTF TeX Toolchain typically goes from TeX into PDF, Postscript, etc. Although intended to work with SGML, the openjade toolchain also supports the use of XML. Main strength of standard stylesheets is that they are easily customizable. Parameters found in params.xsl and (for HTML) chunk.xsl. Example: ]]> Separate XSLT stylesheets for processing a single file and for generating multiple files (chunking). Example of generating a single file: xsltproc -o outfile.html /usr/share/sgml/docbook-xsl/html/docbook.xsl input.xml Example of generating multiple files: xsltproc /usr/share/sgml/docbook-xsl/html/docbook.xsl input.xml Generally a two-stage process: Generation of FO from XML Generation of PDF from FO Example: xsltproc -o manual.fo /usr/share/sgml/docbook-xsl/fo/docbook.xsl manual.xml Fop -fo manual.fo -pdf manual.pdf Example of generating multiple files: xsltproc /usr/share/sgml/docbook-xsl/html/docbook.xsl input.xml

Emacs with psgml Emacs with psgml mode for entering elements and performing validation vim with macros Vim with macros to speed entry epcEdit http://www.epcedit.com/ - commercial editor for both Windows and Linux ArborText Epic http://www.arbortext.com/html/products.html - comprehensive suite of both editing and processing tools SoftQuad XMetal http://www.softquad.com/ - XML editor Most XSL processors include validation, but there are specific tools. xmllint - part of libxml xmllint --valid --noout file.xml http://saxon.sourceforge.net/ Java-based, also "Instant" versions for Windows Developed by Michael Kay Incorporates experimental XSLT features java com.icl.saxon.StyleSheet inputfile stylesheet http://xml.apache.org/ Java-based (also a C++ version) Developed by Apache Project Widely used in open source community java org.apache.xml.xalan.xslt.Process -IN inputfile -XSL stylesheet -OUT outfile http://xmlsoft.org/XSLT/ C program. Binaries available for Linux and Windows. Developed by Daniel Veillard from Red Hat, originally for GNOME Project Multiple commands: xsltproc - XSLT processing xmllint - XML validation and formatting Extremely fast xsltproc -o outputfile stylesheet inputfile http://xml.apache.org/fop/ Java-based Developed by Apache Project Current version outputs to PDF, MIF, text and PCL. Examples: Fop -fo inputfile -pdf outputfile Fop -fo manual.fo -pdf manual.pdf Can be used in conjunction with Xalan to directly process files: Fop -xsl mystyles.xsl -xml manual.xml -pdf manual.pdf http://users.ox.ac.uk/~rahtz/passivetex/ Series of TeX macros Developed by Sebastian Rahtz Current version outputs to PDF or TeX. Examples: pdfxmltex FOinputfile pdfxmltex manual.fo You actually run the command twice on the same FO file to resolve all references. Installation can be a bit tricky, but output is regarded as high quality. While designed for SGML, openjade and jade can also work with XML. openjade -t sgml -i html -d DSSSL-stylesheet openjadepath/pubtext/xml.dcl filename.xml More info at: http://openjade.sourceforge.net/ http://www.jclark.com/jade/ Other tools provide wrappers to openjade/jade, including: sgmltools-lite http://sgmltools-lite.sourceforge.net/ sgml2x http://sgml2x.sourceforge.net/ DocParse http://www.commandprompt.com/products_DocParse.lxp - converts HTML into DocBook ArborText Epic http://www.arbortext.com/html/products.html - comprehensive suite of both editing and processing tools RenderX XEP http://www.renderx.com/products.html - a FO to PDF rendering engine xt http://www.jclark.com/xml/xt.html - one of original XSLT processors. Less frequently used now. docbook2x http://docbook2x.sourceforge.net/http://docbook2x.sourceforge.net/ - converts DocBook to man and Texinfo pages refdb http://refdb.sourceforge.net/ - creates reference databases and bibliographies from DocBook More tools can be found at: http://www.freshmeat.net/ http://www.sourceforge.net/ Processing can be automated through using Makefiles. Example: Now make all will generate both HTML and PDF. Because XML files are all text based, the Concurrent Versions System (CVS) works extremely well. http://www.cvshome.org/ http://www.lodestar2.com/people/dyork/talks/cvs/

Creation of presentation slides from DocBook XML Can create HTML (with or without frames) and FO Uses DocBook elements within specific heirarchical framework. Formatting controlled through CSS file. Downloadable from DocBook Open Repository (SourceForge). Example: ... ... ... ... ]]> Creation of web sites from a collection of DocBook XML files Uses most DocBook elements within specific framework. Has separate files that control page navigation and heirarchy. Downloadable from DocBook Open Repository (SourceForge). See nwalsh.com as an example. Example of main file: ]>

Introduction

Norman Walsh, DSSSL, SGML, XML, DocBook, Website This small, somewhat contrived website demonstrates the Website document type. Website provides a system for building static Websites from XML content. A text-only version is also available, demonstrating how multiple presentations can be derived from the same sources.

A website is a collection of pages organized, for the purposes of navigation, into one or more hierarchies. In Website, each page is a separate XML document authored according to the Website DTD, a customization of DocBook.

]]>

Yes, if you are willing to: Sacrifice some formatting control Experience complexity in setting up tools No, if you: Need precise formatting control Do not have the technical expertise to set up the tools OASIS DocBook home page (also mailing lists): http://www.oasis-open.org/docbook/ "DocBook:The Definitive Guide" home page: http://www.docbook.org/ DocBook Open Repository: http://docbook.sourceforge.net/ Books: DocBook:The Definitive Guide, by Norman Walsh and Leonard Muellner, published by O'Reilly & Associates, October 1999 (new version available online) Linux Documentation Project Author Guide: http://www.linuxdoc.org/LDP/LDP-Author-Guide/ Norman Walsh's documentation pages: http://www.nwalsh.com/docs/ Mitel NSSG documentation process: http://www.e-smith.org/docs/docprocess.html Contact Info: Dan York, Director of Training Mitel Networks Corporation Network Server Solutions Group dan_york@mitel.com dyork@Lodestar2.com (personal address) +1-613-263-4312 This presentation will be available from: http://www.lodestar2.com/people/dyork/talks/docbook/