Docbook for Online and Printed Documentation

Sagehill Enterprises

DocBook for Online and Printed Documentation

Bob Stayton Sagehill Enterprises [email protected] Writers UA Conference Hollywood, CA, 29 March 2004

What is DocBook?

►DTD for technical documentation. ►Related stylesheets and tools. ►Started in 1991 as SGML. ►OASIS standard since 1998. ►General markup useful for other content types.

29 March 2004 DocBook for Online and Printed Documentation 2

Organization for the Advancement of Structured Information Standards (OASIS)

OASIS: http://www.oasis-open.org

OASIS DocBook: http://www.oasis- open.org/committees/tc_home.php?wg_abbrev=docbook

Why use DocBook?

►Content separate from format. ►Multiple output formats from single source. ►Open to computer processing. • Validation. • Database • Repurposing. ►Great free publishing tools.

29 March 2004 DocBook for Online and Printed Documentation 3

Content marked up by semantics, not format. Can adapt it to many output formats. Can do formatting accessible to sight-impaired, for example.

Output formats

► HTML ► XHTML ► HTML Help ► XSL-FO ► PDF and PostScript ► JavaHelp ► man pages ► TeX ► RTF

29 March 2004 DocBook for Online and Printed Documentation 4

Some require two steps.

Also DocBook Slides customization for doing presentation slides (not these slides).

Also DocBook Website customization for building a whole website.

Great free publishing tools

►Stylesheets for HTML and print output. ►Customizable. ►Selection of fast processors. ►Available on all platforms.

29 March 2004 DocBook for Online and Printed Documentation 5

People use DocBook because of the great stylesheets.

Not tied to a particular vendor’s products.

Exchange between platforms.

DocBook is not …

►Microsoft Word ►FrameMaker ►Quark Express ►Simple

29 March 2004 DocBook for Online and Printed Documentation 6

Not a word processor. Not a visual page design and layout tool.

Not tied to a single platform.

Not easy to use.

Learning curve

►A lot more tags than HTML. ►Structure rules strictly enforced. ►Open source tools individually documented. ►Getting tools to work together is complicated.

29 March 2004 DocBook for Online and Printed Documentation 7

Writers need to adapt to structure rules.

Documentation completeness and quality varies among components.

Tools still under development, so changes to one component can break others. Full use requires keeping up with mailing list.

Best for …

►Multiple output formats. ►Multiple releases over time. ►Large documentation sets. ►Batch processing environment. ►Shared authoring.

29 March 2004 DocBook for Online and Printed Documentation 8

Not the best tool for: one-off documents format-driven documents like magazines single-person operation

DocBook community

►Mailing lists • docbook-apps for processing questions. • docbook for DTD questions. ►DocBook SourceForge project • Stylesheet CVS files • Bug reports. ►DocBook Wiki • User contributions.

29 March 2004 DocBook for Online and Printed Documentation 9

Mailing lists: mailto: [email protected] mailto: [email protected] DocBook SourceForge project http://docbook.sf.net http://sourceforge.net/projects/docbook/ DocBook Wiki http://docbook.org/wiki/moin.cgi/

What do you need?

►Document Type Definition (DTD) ►Writing tools ►Stylesheets ►Processing tools

29 March 2004 DocBook for Online and Printed Documentation 10

DTDs

►Available in XML and SGML. ►OASIS maintains DocBook DTDs. ►Current version is 4.3. ►401 elements. ►Customizable: easy to subset or extend. ►Experimental XML Schema available.

29 March 2004 DocBook for Online and Printed Documentation 11

DocBook XML DTD available from: http://www.oasis-open.org/docbook/xml/

Customization guidance: http://docbook.org/tdg/en/html/ch05.html http://www.sagehill.net/xml/customdtd/index.html

Experimental DocBook schema (XML Schema, RelaxNG) http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/docbook/schema

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

29 March 2004 DocBook for Online and Printed Documentation 12

http://www.xmlmind.com/xmleditor/ http://www.morphon.com/ http://www.syntext.com/products/serna/ http://www.xmetal.com/ http://www.arbortext.com/html/epic_editor_overview.html

List of writing tools: http://docbook.org/wiki/moin.cgi/DocBookAuthoringTools

Possibilities: OpenOffice, MS Word 2003, WordPerfect 11.

Stylesheets – two kinds

►XSL stylesheets • Work with XML only. • HTML or XHTML output • XSL-FO output for print ►DSSSL stylesheets • Work with SGML or XML. • HTML output • Jadetex output for print ►Both written by Norman Walsh.

29 March 2004 DocBook for Online and Printed Documentation 13

Document Style Semantics and Specification Language

XSL processing tools

►XSLT processor • Converts XML to HTML or XSL-FO ►XSL-FO processor • Converts XSL-FO to PDF, PostScript ►HTML Help Workshop • Converts HTML to MS Help

29 March 2004 DocBook for Online and Printed Documentation 14

Print output

XML file XSLT Processor FO file DocBook Stylesheet

FO Processor PDF file

29 March 2004 DocBook for Online and Printed Documentation 15

HTML Help output

XML file XSLT HTML files Processor .hhp .hhc files DocBook Stylesheet

HTML Help .chm file Workshop

29 March 2004 DocBook for Online and Printed Documentation 16

http://docbook.sourceforge.net/release/xsl/current/doc/htmlhelp.html

XSLT processors

►Saxon • Requires Java runtime ►xsltproc • Part of the XSLT C library for GNOME ►Xalan-Java • Requires Java runtime ►Others

29 March 2004 DocBook for Online and Printed Documentation 17

http://xml.apache.org/xalan-j/ http://saxon.sourceforge.net/ http://xmlsoft.org/XSLT/xsltproc2.html

Others include: Microsoft MSXML http://msdn.microsoft.com/xml/ Sablotron http://www.gingerall.com/charlie/ga/xml/p_sab.xml James Clark’s XT http://www.jclark.com/ 4XSLT (Python) http://fourthought.com/4Suite/4XSLT/

XSL-FO processors

►Apache FOP (free) • Requires Java runtime ►Commercial products • Antenna House’s XSL Formatter • RenderX’s XEP • Unicorn’s Formatting Objects

29 March 2004 DocBook for Online and Printed Documentation 18

FOP: http://xml.apache.org/fop/ PassiveTeX: http://www.tei-c.org.uk/Software/passivetex/

XSL Formatter: http://www.antennahouse.com/ XEP: http://www.renderx.com/ Unicorn Formatting Objects: http://www.unicorn-enterprises.com/

Writing DocBook

►XML declaration ►DOCTYPE declaration ►Root element

29 March 2004 DocBook for Online and Printed Documentation 19

Root element contains all content.

DocBook document

Using a mouse A mouse is used for blah blah. Mouse buttons A mouse has one, two, or three buttons.

29 March 2004 DocBook for Online and Printed Documentation 20

DOCTYPE specifies root element.

PUBLIC identifier is optional, replace with the keyword SYSTEM if not there.

System identifier is required.

Root element contains all content.

Document must be valid to work with the stylesheets.

Article – alternative to book

►Less than a book. ►Like chapter, but not numbered. ►Good for: •Help files. • White paper. • Short HOWTO.

29 March 2004 DocBook for Online and Printed Documentation 21

Standalone document.

Collection in a book.

Block examples Paragraph Text Bullet list First Numbered list Item 1

29 March 2004 DocBook for Online and Printed Documentation 22

Formal displays

►Elements •figure •example •table • equation ►Numbered and titled. ►Each can contain appropriate content.

29 March 2004 DocBook for Online and Printed Documentation 23

Graphics

► • Contains one or more – Each contains one ►Separate object for each output format. ►Select by role attribute. ►Replaces simpler element

29 March 2004 DocBook for Online and Printed Documentation 24

Cross reference with xref

Using a Mouse ... See .

►Output: See Chapter 3, Using a Mouse.

29 March 2004 DocBook for Online and Printed Documentation 25

Cross reference with link

id="Mouse"> Using<title>Using aa MouseMouse Use... your mouse formouse for ... ►Output: ►Output: Use your Use your mouse mouse ... for ...

29 March 2004 DocBook for Online and Printed Documentation 26

DocBook XSL stylesheets

►Written in XML using XSL namespace. ►Designed for customization. ►Under active development. ►Use any conforming XSL processor.

29 March 2004 DocBook for Online and Printed Documentation 27

Download stylesheets from http://docbook.sourceforge.net/

Customizable

►Modular design (~100 files) ►Reusable named templates. ►Empty, user-defined templates. ►Parameterized (~220 parameters) ►Title page tools. ►Templates for generated text.

29 March 2004 DocBook for Online and Printed Documentation 28

Stylesheet subdirectories

►Install anywhere, such as: \docbook\docbook-xsl-1.65.1\ html Stylesheet files for HTML output. xhtml Stylesheet files for XHTML output. fo Stylesheet files for FO output. htmlhelp Customization for HTML Help. javahelp Customization for JavaHelp.

29 March 2004 DocBook for Online and Printed Documentation 29

Support subdirectories

common Shared stylesheet modules, including languages. doc Documentation for the stylesheets in browsable HTML. extensions Program files that extend XSL for particular processors. images Icons and other images used in the output. lib Stylesheet modules shared among many outputs.

29 March 2004 DocBook for Online and Printed Documentation 30

Main stylesheet files

►Single large HTML file output: html\docbook.xsl ►Multiple small HTML files: html\chunk.xsl ►HTML Help htmlhelp\htmlhelp.xsl ►FO output suitable for FO processor: fo\docbook.xsl

29 March 2004 DocBook for Online and Printed Documentation 31

These stylesheets load all the other necessary stylesheet modules. Use one on your XSLT command line.

Installing XSLT processor

► xsltproc • Windows binaries available. • Need all four of these packages: – libxml2 – libxslt – iconv – zlib ► Saxon and Xalan • Need Java runtime environment. • Download and add to CLASSPATH. • DocBook extensions available.

29 March 2004 DocBook for Online and Printed Documentation 32

Installation help: http://www.sagehill.net/docbookxsl/ToolsSetup.html

xsltproc Windows binaries: http://www.zlatkovic.com/projects/libxml/index.html

xsltproc source: http://xmlsoft.org

Using xsltproc

►HTML output: xsltproc --output myfile.html \docbook-xsl\html\docbook.xsl myfile.xml ►FO output: xsltproc --output myfile.fo \docbook-xsl\fo\docbook.xsl myfile.xml

29 March 2004 DocBook for Online and Printed Documentation 33

You can use forward slashes in xsltproc arguments.

Using Saxon

►HTML output: java -cp "\saxon\saxon.jar: \docbook-xsl\extensions\saxon65.jar" com.icl.saxon.StyleSheet -o myfile.html myfile.xml \docbook-xsl\html\docbook.xsl

29 March 2004 DocBook for Online and Printed Documentation 34

Generating HTML Help

►Generate HTML: xsltproc --base.dir helpfiles \docbook-xsl\htmlhelp\htmlhelp.xsl myfile.xml ►Generate MS Help: cd helpfiles hhc htmlhelp.hhp

29 March 2004 DocBook for Online and Printed Documentation 35

Generating PDF with FOP

►Generate FO: xsltproc --output myfile.fo \docbook-xsl\fo\docbook.xsl myfile.xml ►Generate PDF: fop.bat -fo myfile.fo –pdf myfile.pdf

29 March 2004 DocBook for Online and Printed Documentation 36

Using parameters

►Named variables in stylesheet. ►Examples: • Specify CSS stylesheet name. • Turn on section numbering. • Shade verbatim output. ►Each processor has its own command syntax.

29 March 2004 DocBook for Online and Printed Documentation 37

Parameter reference:

http://docbook.sourceforge.net/release/xsl/current/doc/reference.html

“verbatim” includes programlisting and literallayout.

Parameter example

xsltproc --output myfile.html \ --stringparam html.stylesheet style.css \ --stringparam shade.verbatim 1 \ html\docbook.xsl myfile.xml

► Output

29 March 2004 DocBook for Online and Printed Documentation 38

HTML Help parameters

►Control names of generated files. ►Control buttons displayed. ►Control table of contents display. ►Control character encoding.

29 March 2004 DocBook for Online and Printed Documentation 39

HTML Help parameter documentation: http://docbook.sourceforge.net/release/xsl/current/doc/html/rn20.html

Customization driver file

►New stylesheet that combines: • Standard DocBook XSL templates • Your customizations. ►Kept separate, so updates are easy. ►Used in place of DocBook stylesheet.

29 March 2004 DocBook for Online and Printed Documentation 40

Reference: http://www.sagehill.net/docbookxsl/CustomMethods.html

Driver file content

►Standard XSL stylesheet elements. ►Pull in stock DocBook with: ►Parameter settings. ►Replacement templates. ►New generated text.

29 March 2004 DocBook for Online and Printed Documentation 41

Must use forward slashes in XSL hrefs.

Customization example

29 March 2004 DocBook for Online and Printed Documentation 42

Keep a good XSLT reference handy, such as Michael Kay’s XSLT Programmer’s Reference.

Special DocBook features

►Glossaries ►Bibliographies ►Indexes

29 March 2004 DocBook for Online and Printed Documentation 43

Special processing

►Profiling ►Modular documentation. ►Olinking.

29 March 2004 DocBook for Online and Printed Documentation 44

Profiling

►Multiple versions from same file. ►aka Conditional text. ►Marked with profiling attributes: • os, userlevel, condition, etc. ►Use profile-docbook.xsl stylesheet. ►Select conditions with parameters: profile.os="linux"

29 March 2004 DocBook for Online and Printed Documentation 45

Reference: http://www.sagehill.net/docbookxsl/Profiling.html

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.

29 March 2004 DocBook for Online and Printed Documentation 46

Reference: http://www.sagehill.net/docbookxsl/ModularDoc.html

System entities are the old way of doing it. Declared in the DTD or DOCTYPE and referenced in the document.

Xinclude does not require declaration in the DTD.

Olinking

►Create olink database from documents. ►Processor reads the database. ►Can generate link text. ►Can link to base URI per document. ►Creates dependencies between docs.

29 March 2004 DocBook for Online and Printed Documentation 47

Reference: http://www.sagehill.net/docbookxsl/Olinking.html

More flexible, more complicated. Stylesheet reports unresolved olinks.

Supports different locations for HTML documents. Can generate relative path links.

For more information

►Slides PDF with notes: • http://www.winwriters.com/ohc04/suppmatl ►DocBook SourceForge project: • http://docbook.sf.net/ ►DocBook: The Definitive Guide • http://docbook.org/tdg/en/html/docbook.html ►Sagehill website: • http://www.sagehill.net/docbookxsl/

29 March 2004 DocBook for Online and Printed Documentation 48