Dan York Product Line Mgr, SME Server Mitel Networks Corporation Network Server Solutions Group dan_york@mitel.com June 28, 2002 Ottawa Linux Symposium Ottawa, Ontario, Canada 2002 Dan York Introduction Getting started Creating a first document More DocBook elements Stylesheets Other output formats Profiling Extensions Other tools Resources

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 - http://www.oasis-open.org/docbook/ 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 Very 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 MIF (Adobe FrameMaker) PDF PostScript RTF (Microsoft) TeX Text 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... ... ... ... ... ...

]]>

An editor The DocBook XML DTD (optional) The DocBook XSLT stylesheets An XSLT processor 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 XSLT processors also validate the XML, so you need access to the DocBook XML DTD Standard header to a DocBook XML file is: ]]> If used, most XSLT processors require you to be online xsltproc supports the use of XML Catalogs which map identifiers to locally installed DTDs If you are not online and do not have XML Catalog support, you need to change header to path where DTD is installed ]]> Download the XML v4.1.2 DTD from: http://www.oasis-open.org/docbook/xml/index.shtml Extract into a directory - LSB proposal would be /usr/share/sgml/docbook/xml-dtd-4.1.2 "Standard" set of "modular" stylesheets maintained primarily by Norman Walsh. Two sets of stylesheets: XSL DSSSL Available from http://docbook.sourceforge.net/ Specifically http://sourceforge.net/project/showfiles.php?group_id=21935 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. Download the .tgz or .zip from http://sourceforge.net/project/showfiles.php?group_id=21935 Current version is 1.51.1. Extract them into a directory - by LSB proposal it would be /usr/share/sgml/docbook/docbook-xsl-1.51.1/ (for example) Will see a variety of subdirectories relating to output formats 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 Need to download both libxml2 and libxslt xsltproc -o outputfile stylesheet inputfile 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 You should have: An editor DocBook DTD installed in /usr/share/sgml/docbook/xml-dtd-4.1.2/ XSL stylesheets in /usr/share/sgml/docbook/docbook-xsl-1.51.1/ An XSLT processor Let's go...

Always starts with header: ]]> May have to change URL to local path if offline Will usually be a <book> or <article> (need to change header line appropriately) If <book>, will be composed of multiple <chapter> elements each with sections inside If <article>, will be composed of multiple section elements Indenting and all whitespace is ignored except in some verbatim elements 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.

This is an introductory paragraph. This is a paragraph. Blah, blah, blah... This is more text To install this program, you need to execute some script.

]]> For clarity in these slides, I have environment variable for path: $ export DB="/usr/share/sgml/docbook/docbook-xsl-1.51.1" Process the slides into an HTML page: $ xsltproc -o sample.html $DB/html/docbook.xsl sample.xml View HTML document in browser. Referred to as "chunking" Simple matter of calling chunk stylesheet $ xsltproc $DB/html/chunk.xsl sample.xml

Provides a bulleted list and maps to a ]]> in HTML. Item A Item B Item C ]]> Can contain other DocBook elements inside of <listitem> elements 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.]]>]]> Docbook page]]> Internal links based on id attributes added to other elements 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... ]]>

Main strength of standard stylesheets is that they are easily customizable. Parameters found in params.xsl or in HTML in $DB/doc/html/index.html. Example: mystyle.xsl ]]> Call your customization layer instead of the standard stylesheet xsltproc -o sample.html mystyle.xsl sample.xml Beyond setting parameters, you can modify XSLT "templates" to override default behavior Requires at least minimal knowledge of XSLT Example: ]]> What if you want to generate single HTML pages and multiple HTML pages with the same basic customizations? Could do two stylesheets that differ only in calling docbook.xsl or chunk.xsl Problem keeping changes in sync between stylesheets Solution is to have one main stylesheet and two "driver" files Example: XSLT stylesheets for Linux Documentation Project Consist of three files: ldp-html-common.xsl - main stylesheet that contains actual customizations ldp-html.xsl - file to call for single HTML pages - imports ldp-html-common.xsl ldp-html-chunk.xsl - file to call for multiple HTML pages - imports ldp-html-common.xsl Allows for customizations specific to single or multiple files to be placed in appropriate files. Usage: xsltproc -o howto.html ldp-html.xsl howto.xml xsltproc ldp-html-chunk.xsl howto.xml ldp-html.xsl: ]]> ldp-html-chunk.xsl: ]]> ldp-html-common.xsl images/ ]]>

Generally a two-stage process: Generation of FO from XML Generation of PDF from FO Example: xsltproc -o sample.fo $DB/fo/docbook.xsl sample.xml fop.sh -fo sample.fo -pdf sample.pdf 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. Creates compiled Windows Help file (.CHM) viewable and fully searchable on Windows systems Two stage process: Process the file into HTML files, with extra HTML Help files: xsltproc $DB/htmlhelp/htmlhelp.xsl manual.xml Bring file into Microsoft's "Windows HTML Help Workshop" to compile into single .CHM file Can (of course!) build a customization layer that imports htmlhelp.xsl AWT FOP, displays into a Java graphic window Java Help Separate XSLT stylesheet similar to HTML Help MIF FOP or SGML toolchain PCL FOP, though support is limited PostScript FOP, similar to PDF RTF FOP (limited support) or SGML toolchain SVG FOP Text FOP (limited support) or through generating single HTML page and then dumping the page to text using a text browser like "lynx" or "links" XHTML Separate XSLT stylesheets similar to HTML

What if you want to have two (or more) documents that share most of the data in common? Ex: Installation manual for Linux, Windows, and Mac Document for Intel and Alpha architectures User guide with beginner and advanced variants Document with internal and public versions Single document with multiple embedded languages DocBook implements this in profiling Similar to FrameMaker's "conditional text" feature Described in $DB/doc/tools/profiling.html Works through adding additional attributes to elements. Example: You must first have full access to the system. On Windows 95/98/NT, run INSTALL.EXE and follow the instructions. In Linux, install foo-1.0-1.i386.rpm. ]]> Special stylesheets will now make a first pass through to extract relevant elements, then do further processing. Attributes can be added to individual paragraphs or to entire sections Variants of standard XSL stylesheets provided with profile- prefix Called with profile.xxxx parameter and value to set profile The exact method of providing a parameter and value on the command line varies with each XSLT processor. Examples: $ xsltproc -o sample.html -stringparam "profile.os" "linux" $DB/html/profile-docbook.xsl sample.xml $ saxon -o sample.html sample.xml $DB/html/profile-docbook.xsl "profile.userlevel=beginner" Multiple values separated by semi-colons (by default), as in: xsltproc ... -stringparam "profile.os" "linux;mac" ... Can be imported into a customization layer

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.

]]>

Most XSL processors include validation, but there are specific tools. xmllint - part of libxml xmllint --valid --noout file.xml 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 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/

OASIS DocBook home page (also mailing lists): http://www.oasis-open.org/docbook/ docbook-apps mailing list: http://lists.oasis-open.org/archives/docbook-apps/ "DocBook:The Definitive Guide" home page: http://www.docbook.org/ Includes documentation in DocBook Wiki 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, PLM, SME Server 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/