DocBook XSL: The Complete Guide

Fourth Edition

Bob Stayton

September, 2007

PO Box 2911
Santa Cruz CA

A PDF version of this document is available for purchase from Sagehill Enterprises.

DocBook Consulting Services available.

The author of this book is available for helping with DocBook or other XML publishing projects.
What is DocBook?
Changes in the Fourth Edition
Part I. Setting up the tools
Chapter 1. Introduction
How this book is organized
Online resources for finding solutions to problems
Chapter 2. XSL processors
XSLT processors
XSL-FO processors
Portability considerations
Chapter 3. Getting the tools working
Installing the DocBook DTD
Finding the DTD during processing
Character entities
Installing the DocBook stylesheets
Installing an XSLT processor
Installing xsltproc
Using xsltproc
Installing Saxon
Using Saxon
Installing Xalan
Using Xalan
Installing an XSL-FO processor
Installing FOP
Using FOP
Using other XSL-FO processors
XSL servers
Chapter 4. DocBook 5 tools
DocBook 5 differences
DocBook 5 namespace
DocBook 5 schemas
Universal linking in DocBook 5
Uniform metadata elements
Entities with DocBook 5
Separate DocBook 5 entities file
DocBook character entities
Processing DocBook 5
DocBook 5 validation
DocBook 5 XSLT processing
Chapter 5. XML catalogs
Why use XML catalogs
How to write an XML catalog file
Resolve the DTD location
Locate an XSL stylesheet
Map a web address to a local file
Map many references with rewrite entries
Using multiple catalog files
Example DocBook catalog file
How to use a catalog file
Using catalogs with Saxon
Using catalogs with Xalan
Using catalogs with xsltproc
Part II. Stylesheet options
Chapter 6. Using stylesheet parameters
Parameters on the command line
Parameters in a file
Chapter 7. HTML output options
Single HTML file
Processing part of a document
Chunking into multiple HTML files
Chunk filenames
Chunked files output directory
Fast chunking
Table of contents chunking
Controlling what gets chunked
Output encoding for chunk HTML
Specifying the output DOCTYPE
Indenting HTML elements
Single file options with onechunk
Name the file using an id
Putting the file elsewhere
Specify the output encoding and DOCTYPE
Using CSS to style HTML
Styling section headings with CSS
Styling displays with CSS
Adding custom class attributes
Generating id attributes
Chapter and section numbering
Depth of section numbering
Docbook icon graphics
Admonition graphics
Navigational icons
Callout icons
Date and time
Chapter 8. Printed output options
Page layout
Paper size
Finished page size
Left and right margins
Top and bottom margins
Indenting body text
Landscape documents
Double sided
Double spacing
Body and title font families
Font sizes
Using renderas to style section titles
Chapter and section numbering
Depth of section numbering
Numbering book parts
Page breaking
Keep-together processing instruction
Soft page breaks
Hard page breaks
PDF bookmarks
Extra blank lines
Cross reference page numbers
Docbook icon graphics
Admonition graphics
Callout icons
Printing one chapter
Crop marks
Part III. Customizing DocBook XSL
Chapter 9. Customization methods
Customization layer
Writing a customization layer
Using a customization layer
Customizing both HTML and FO
Using catalogs with customizations
Setting parameters
Attribute sets
Completing placeholder templates
Generating new templates
Generated text
Default generated text
Customizing generated text
Replacing templates
Finding the right template
Import precedence
Passing parameters
Utility templates and modes
Adding new templates
Formatting determined by attribute value
Adding processing steps
Handling new elements
Template selection rules
Processing instructions
Customizing DocBook 5 XSL
DocBook 5 customization details
Annotations customization
Chapter 10. General customizations
Custom section numbering
Label punctuation
Tables of contents (TOC)
Which components have a TOC
Levels in book and chapter TOCs
Customized TOC levels
Turning on section TOCs
Keeping selected titles out of the TOC
Adding elements to a TOC
Customizing TOC presentation
Customizing by TOC context
Figure, table, and other titles
Formal title placement
Formal title numbering
Formal title customization
Person names
Chapter 11. Title page customization
Create a titlepage spec file
HTML titlepage specs
Special titlepages
Generate custom XSL templates
Add to customization layer
Modify individual element templates
Chapter 12. HTML customizations
Generate custom class values
HTML headers and footers
Adding extra lines
Navigational labels or graphics
Brief headers and footers
Bread crumbs
Replace headers and footers
Server-side includes
Inserting external HTML code
In the page header
In the HEAD element
In the page content
HTML HEAD elements
Adding CSS style rules
Embedding CSS styles
Adding a date timestamp
Removing the HEAD element
BODY attributes
Changing the <h> levels
HTML frameset
Chunking customization
How chunking works
Chunking templates
Separate legalnotice
Filename of the legalnotice chunk
Footer link to legalnotice
More than one legalnotice
Head links for legalnotice
Separate revhistory
Return to top
Customized hrefs
Chapter 13. Print customizations
Document level properties
Title fonts and sizes
Book titles
Chapter titles
Other component titles
Section titles
Figure, table, and other titles
Print title pages
Title page attribute-sets
Title page spec file
Title page element templates
Custom title page layout
Template sequence for book title pages
Additional front or back matter
Book covers
Custom page design
Default page masters
Declaring custom page masters
Using custom page masters
Landscape pages
Custom page sequences
Print TOC control
TOC Page margins
TOC title
Styling print TOC entries
TOC page numbering
Part TOC on part titlepage
Editable table of contents
Running headers and footers
Default headers and footers
Changing the header or footer text
Running section titles
Graphic in header or footer
Multi-line header or footer
Changing header or footer styles
Allocating widths in the headers and footers
Allocating height for headers and footers
Page numbering style
Borders and background shading
Customizing inline text
Subscripts and superscripts
Underline and strike-through
Customizing admonitions
Side-by-side formatting
Side floats
A sidebar as side float
Margin notes
Custom margin notes
Custom side float
Clearing a side float
Multi-columns and spans
Page column spans
Adding a font
Locate the font file
Configuring fonts in XSL-FO
Adding a new font to FO output
Numbering paragraphs
Adding line breaks
Part IV. Special DocBook features
Chapter 14. Bibliographies
Bibliography entries
Bibliography database
Bibliography database catalog entry
Citing bibliographic entries
Numbered bibliography entries
Sorting a bibliography
Customizing bibliography output
ISO 690 bibliography standard
Bibliography title
RefDB bibliographic database
Chapter 15. Cross references
Cross references within a document
Linking from other elements
Options for generated xref text
Cross references between documents
Linking to websites
Breaking long URLs
DocBook 5 cross references
Customizing cross references
Customizing with an xrefstyle attribute
Modifying gentext templates
Customizing cross reference behavior
Customizing cross reference typography
Specialized cross references
Chapter 16. Footnotes
Footnote numbers and symbols
Formatting footnotes in HTML
Formatting footnotes in print
End notes
Chapter 17. Glossaries
Glossary formatting
Glossary formatting in print
Linking to a glossary entry
What about link and xref?
Glossary database
Glossary database catalog entry
Links in a glossary collection
Glossary sorting
Chapter 18. Graphics
Elements for graphics
Selecting file formats
Adding graphics formats
Stylesheet's selection process
Select by role
Select by format
Image sizing
Graphic size extension
Different sizes for HTML and FO output
Landscape images
Image alignment
Background color
Titles and captions
Alt text
Long descriptions
Figure floats
Inline graphics
Graphic file locations
HTML output directory
FO input directory
SVG images
Using calspair coords
Using imagemap coords
Chapter 19. Indexes
Adding indexterms
Specialized indexes
Outputting an index
Cleaning up an FO index
Internationalized indexes
index.method = "basic"
index.method = "kosek"
index.method = "kimber"
Formatting HTML indexes
Formatting print indexes
Index columns
Index titles
Formatting index entries
Index punctuation
XSL-FO processor indexing extensions
Customizing indexing templates
Chapter 20. Languages, characters and encoding
Document encoding
Output encoding
Saxon output character representation
Special characters
Special characters in output
Space characters
Missing characters
Language support
Using the lang attribute
Using language parameters
Language codes
Extending the set of languages
Text direction
Chapter 21. Lists
List titles
List spacing
List vertical spacing
List horizontal spacing
itemizedlist options
Different bullet symbol
Print properties for itemizedlist
orderedlist options
Different numbering style
Number continuation
List starting number
Print properties for orderedlist
variablelist options
Multiple term elements
Variable list formatting in print
Variable list formatting in HTML
simplelist options
Chapter 22. Math
Plain text math
Graphic math
Math in SVG
Equation numbering
Chapter 23. Modular DocBook files
Using XInclude
Selecting part of a file
Including plain text
XInclude fallback
XIncludes and entities for filenames
XIncludes and XML catalogs
XIncludes and directories
XIncludes and graphics files
Entity references in included text
XIncludes in XML editors
Validating with XIncludes
DTD customizations for XIncludes
Modular cross referencing
Modular sections
Shared text entities
Putting customized entities in the DTD
Processing your modular documents
Java processors and XIncludes
Using an XSL-FO processor with XIncludes
Using a module more than once in the same document
Reusing content at different levels
Using modified id values
Inserting dynamic content
Chapter 24. Olinking between documents
How to link between documents
Example of target data
Universal olinking in DocBook 5
Details to watch out for
Target database location
Using a sitemap
Olinking in print output
Setting up PDF olinking
Open target in new window
Linking between HTML and PDF documents
Page references in olinks
Generating olink text
Default olink text
Adding the document title
Using local styles
Using xrefstyle attributes
Customizing the olink template
Formatting olinks
Options for resolving olinks
Language fallback option
Debugging olinks
Processing options
Naming your data files
Using Makefiles with olinking
Using XInclude in the database document
Using catalogs for olink data
Olinks with profiling (conditional text)
Remote olink targets
Customizing olink XSL templates
Target database additional uses
Chapter 25. Other output forms
Generating XHTML
Validating XHTML
Customizing XHTML
Generating HTML Help
Processing options
Formatting options
Additional resources
Eclipse Platform help system
Formatted plain text
Refentry to man
Man to refentry
Microsoft Word
Chapter 26. Profiling (conditional text)
Marking conditional text
Marking small bits of text
Multiple profiling conditions
Processing profiled versions
Single-pass processing
Two-pass processing
Customization and profiling
Validation and profiling
Custom profiling attribute
Adding new profiling attributes
Adding attributes to the DTD
Adding attributes to RelaxNG
Profiling with new attributes
Using the role attribute for profiling
Chapter 27. Program listings
Formatting listings
Tab expansion
Fitting text
Full-width examples
Reducing font size
Breaking long lines
External code files
Missing text
Using XInclude for text inclusions
Annotating program listings
Line annotations
Line numbering
Callouts on imported text
Callouts on graphics
Syntax highlighting
Chapter 28. Q and A sets
Q and A labeling
Q and A formatting
Q and A list of questions
Hiding the answers
Q and A cross references
Chunking Q and A
Q and A in table of contents
Chapter 29. Revision control
Revision elements and attributes
Formatting revhistory
XSL-FO output for revhistory
HTML output for revhistory
Draft mode
Using the status attribute
Profiling on status
Highlighting status
Highlighting changes
Change markup
HTML change output
XSL-FO change output
Chapter 30. Tables
Table width
Table alignment
Full-width tables
Column widths
Cell spacing and cell padding
Row height
Cell alignment
Horizontal alignment
Vertical alignment
Cell rotation
Cell spanning
Horizontal spans
Vertical spans
Table border
Row borders
Column borders
Border styles
Background color
Cell background color
Row background color
Long tables
Table styles in print output attribute-set attribute-set attribute-set
tabstyle template template template template
Table page breaking
Landscape tables
Table title formatting
Table titles without number labels
Table styles in HTML output
Table summary text
HTML table elements
Table template customization for printed output
Table "continued" label
Chapter 31. Website
Creating a webpage XML file
Allowed DocBook elements
Structuring your webpages
Generating your webpages
Build with XSLT only
Build with make
Source files in multiple directories
Linking between pages
Olinks with XSLT build method
Olinks with Make method
Linking to other sites
Adding other content
Website with XML catalogs
Website formatting
Using CSS with Website
Website config attributes
Website stylesheet customization
SilkPage: enhanced Website
Appendix A. A brief introduction to XSL
XSL processing model
Context is important
Programming features
Generating HTML output
Generating formatting objects
Appendix B. Debugging XSL stylesheets
Inserting messages
Using an XSLT debugger