1	Single-source Publishing with DocBook XSL Bob Stayton Sagehill Enterprises DocBook Consulting
2	What is Single-source Publishing? Multiple outputs from single source file. Reusable content. Modular writing. Assembled documents. “Write once, publish many”.
3	Multiple outputs Print, PDF, HTML, slides, Help files. Different product versions. Different user levels. Sight-impaired, WML, text-only.
4	Why Single-source? Reduce redundant writing. Writers can specialize. Update in a single place. Users get more accurate information. Fewer words to translate.
5	What is DocBook? DTD for technical documentation. Related stylesheets and tools. Started in 1991 as SGML, now XML. OASIS standard since 1998.
6	Why use DocBook? Designed for technical documentation. Content kept separate from format. Open to computer processing. Choose your publishing tools. Cross platform Automate your processing.
7	What’s the downside? XML learning curve. Investment in setup. Technical staff needed.
8	Best for … Multiple output formats. Multiple releases over time. Large documentation sets. Batch processing environment. Shared authoring.
9	Who uses DocBook? Sun IBM Microsoft Hewlett Packard Symantec Red Hat, SuSE, Mandrakesoft Linux Documentation Project
10	What do you need? DocBook DTD (XML version). Writing tools. XSL stylesheets. Processing tools.
11	Writing tools Notepad or other text editor. XMLMind’s XMLEditor (free). Morphon’s XML-editor (free). Syntext’s Serna. Blast Radius’s XMetal. Arbortext’s Epic Editor.
12	DocBook XSL stylesheets Open source project on SourceForge. Written in XSL. Stylesheet variant for each output form. Designed for customization. Adapt to corporate style.
13	Getting to HTML
14	XSLT processors xsltproc from Gnome’s xmlsoft.org Saxon 6 from SourceForge Xalan Java from Apache XML project
15	HTML or XHTML Single file or multiple “chunks”. Use CSS classes for styling. Post process with HTML Help Workshop Java Help indexer
16	Getting to print
17	XSL-FO processors XEP from RenderX. XSL Formatter from Antenna House FOP from Apache XML Project
18	Automated print production Stylesheet flows content onto pages. Automatic TOC and index. Automatic page breaking. Writer does not do formatting.
19	Tweaking for print
20	Standard publishing features Front matter Graphics Tables Glossaries Bibliographies Indexes
21	Technical publishing Nested section levels. Numbered figures, tables, examples. Tasks and procedures. Code synopses. Code examples. Running headers and footers.
22	Special features Profiling. Modular documentation. Cross referencing. Localization.
23	Profiling aka Conditional text. Multiple versions from same file. Marked with profiling attributes: os, userlevel, condition, etc. Use a profiling stylesheet. Select conditions at runtime: profile.os="linux"
24	Modular documentation Separate large documents into multiple XML files. System entity != valid document. No DOCTYPE allowed. xrefs won’t resolve. Use Xinclude instead. Modules can be valid documents. Use olink to link between them.
25	Cross referencing Author or generate hotlink text. Define cross reference “styles”. Link within or between documents Between documents: Within a concurrent set. Reference to previously published doc. Reference to remote content.
26	Olinking Create olink database from documents. XSL processor reads the database. Can generate link text. Can link to base URI per document. Creates dependencies between docs.
27	Localization Unicode and other encodings Generated text in 46 languages Index collation Mixed language documents
28	Installing XSLT processor xsltproc Download libxml2 and libxslt C source. Install prebuilt packages. Windows binaries available. Saxon and Xalan Need Java runtime environment. Download and add to CLASSPATH.
29	Using xsltproc HTML output: xsltproc \ --output myfile.html \ /usr/share/docbook/html/docbook.xsl \ myfile.xml FO output: xsltproc \ --output myfile.fo \ /usr/share/docbook/fo/docbook.xsl \ myfile.xml
30	Generating PDF with FOP Convert a .fo file on Unix or Linux: fop.sh -fo myfile.fo -pdf myfile.pdf Convert a .fo file on Windows: fop.bat -fo myfile.fo -pdf myfile.pdf
31	Customization needed Default style is neutral. Functional but boring. Corporate identity requirements. Enhanced functionality: Better navigation. Readability.
32	Customizable stylesheets Modular design. Templates for each element. Small reusable templates. Empty, user-defined templates. Parameterized (~460 parameters)
33
34
35	Customization methods overview Setting parameters Customization layer Attribute sets CSS for HTML Generated text Generating titlepage templates Placeholder templates Customizing templates
36	Customization strategy Methods are a tool kit. Easiest to hardest. Use stylesheet documentation. DocBook XSL: The Complete Guide Free online: http://www.sagehill.net/docbookxsl/ Good XSLT and XSL-FO book(s) DocBook mailing lists
37	Stylesheet parameters What is it: Named variable in stylesheet. Default behavior used otherwise. When to use it: If the right parameter exists. Read the stylesheet doc: http://docbook.sourceforge.net/release/xsl/current/doc/html/
38	Parameter example In HTML output: Add icon graphics for Note, Warning, etc. Collectively known as “admonitions”. Parameter name is admon.graphics
39	Parameter: how to use it Each processor has its own command syntax: xsltproc --output myfile.html \ --stringparam admon.graphics 1 \ html/docbook.xsl myfile.xml Before After
40	Setting multiple parameters Command line good for one-off. Some parameters used consistently. Many parameters = long command line Print page size, margins, etc.
41	Customization layer New stylesheet that combines: Imports DocBook XSL templates Adds your customizations. Kept separate, so updates are easy. Used in place of DocBook stylesheet.
42	Customization layer contains ... Standard XSL syntax. Pull in stock DocBook with: <xsl:import href="path/to/docbook.xsl"/> Parameter settings. Replacement templates. New generated text.
43	Customization example <?xml version='1.0'> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/ Transform" version="1.0"> <xsl:import href="html/docbook.xsl"/> <xsl:param name=“admon.graphics" select="1"/> ... </xsl:stylesheet>
44	Many print parameters <?xml version='1.0'> <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:import href="fo/docbook.xsl"/> <xsl:param name="page.height">9in</xsl:param> <xsl:param name="page.width">7in</xsl:param> <xsl:param name="double.sided">1</xsl:param> <xsl:param name="page.margin.top">0.5in</... <xsl:param name="page.margin.bottom">0.6in</... <xsl:param name="page.margin.inner">0.75in</... <xsl:param name="page.margin.outer">0.5in</... <xsl:param name="body.font.family">Helvetica</... ... </xsl:stylesheet>
45
46	DocBook community Mailing lists docbook-apps for processing questions. docbook for DTD questions. DocBook SourceForge project Stylesheet CVS files Bug reports and feature requests. DocBook Wiki User contributions.
47	Questions? References: DocBook XSL: The Complete Guide http://www.sagehill.net/docbookxsl/ DocBook: The Definitive Guide http://docbook.org/tdg/en/html/docbook.html DocBook SourceForge project: http://docbook.sf.net/