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.
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
17 August 2005 Single-source Publishing with DocBook XSL 43 17 August 2005 Single-source Publishing with DocBook XSL 44
Stock DocBook Customized 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.
17 August 2005 Single-source Publishing with DocBook XSL 45 17 August 2005 Single-source Publishing with DocBook XSL 46
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/
17 August 2005 Single-source Publishing with DocBook XSL 47
Copyright 2005 Bob Stayton 8