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