DocBook XSL: The Complete Guide

Third Edition

Bob Stayton

February 28, 2005

Sagehill Enterprises

PO Box 2911
Santa Cruz CA
95063-2911
Website: 
http://www.sagehill.net

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.
See http://www.sagehill.net/consulting.html
 
Preface
What is DocBook?
Audience
Changes in the Third Edition
Acknowledgements
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
Validation
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
Makefiles
XSL servers
Chapter 4. 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 5. Using stylesheet parameters
Parameters on the command line
Parameters in a file
Chapter 6. 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 7. Printed output options
Page layout
Paper size
Finished page size
Left and right margins
Top and bottom margins
Indenting body text
Landscape
Double sided
Two column
Double spacing
Draft mode
Typography
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
Part III. Customizing DocBook XSL
Chapter 8. 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
Processing instructions
Chapter 9. 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
Customizing TOC presentation
Figure, table, and other titles
Formal title placement
Person names
Chapter 10. 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 11. HTML customizations
HTML headers and footers
Adding extra lines
Navigational labels or graphics
Brief headers and footers
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
HTML frameset
Chunking customization
Separate legalnotice
Filename of the legalnotice chunk
More than one legalnotice
Chapter 12. 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
Custom page design
Default page masters
Declaring custom page masters
Using custom page masters
Print TOC control
Page margins
TOC title
Styling print TOC entries
TOC page numbering
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
Customizing admonitions
Side floats
A sidebar as side float
Margin notes
Custom margin notes
Custom side float
Adding a font
Locate the font file
Configuring a font in FOP
Configuring a font in XEP
Adding a new font to FO output
Part IV. Special DocBook features
Chapter 13. Bibliographies
Bibliography entries
Bibliography database
Bibliography database catalog entry
Citing bibliographic entries
Numbered bibliography entries
Sorting a bibliography
Customizing bibliography output
Bibliography title
Chapter 14. Cross references
Cross references within a document
Options for generated xref text
Cross references between documents
Linking to websites
Customizing cross references
Modifying gentext templates
Customizing with an xrefstyle attribute
Customizing cross reference typography
Specialized cross references
Chapter 15. Footnotes
Footnote numbers and symbols
Formatting footnotes in HTML
Formatting footnotes in print
End notes
Chapter 16. 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
Chapter 17. Graphics
Elements for graphics
Selecting file formats
Adding graphics formats
Stylesheet's selection process
Select by role
Select by format
Image sizing
Different sizes for HTML and FO output
Image alignment
Background color
Titles and captions
Alt text
Long descriptions
Figure floats
Graphics locations
HTML output directory
FO input directory
SVG images
SVG in HTML
Chapter 18. Indexes
Adding indexterms
Specialized indexes
Outputting an index
Cleaning up an FO index
Internationalized indexes
Formatting HTML indexes
Formatting print indexes
Chapter 19. Languages, characters and encoding
Document encoding
Output encoding
Saxon output character representation
Special characters
Special characters in output
Missing characters
Language support
Using the lang attribute
Using language parameters
Language codes
Extending the set of languages
Chapter 20. Lists
List titles
List spacing
List vertical spacing
List horizontal spacing
itemizedlist options
Different bullet symbol
orderedlist options
Different numbering style
Number continuation
List starting number
variablelist options
Variable list formatting in print
Variable list formatting in HTML
Chapter 21. Math
Plain text math
Graphic math
SVG math
DBTeXMath
Bitmap versions for HTML
MathML
Chapter 22. 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
Validating with XIncludes
DTD customizations for XIncludes
Modular cross referencing
Modular sections
Shared text entities
Processing your modular documents
Java processors and XIncludes
Using a module more than once in the same document
Inserting dynamic content
Chapter 23. Olinking between documents
How to link between documents
Example of target data
Details to watch out for
Using a sitemap
Olinking in print output
Setting up PDF olinking
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
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 24. Other output forms
XHTML
Generating XHTML
Validating XHTML
Customizing XHTML
HTML Help
Generating HTML Help
Processing options
Formatting options
Additional resources
JavaHelp
Eclipse Platform help system
Formatted plain text
Refentry to man
Man to refentry
Chapter 25. 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
Using the role attribute for profiling
Chapter 26. Program listings
Fitting text
Reducing font size
Breaking long lines
External code files
Missing text
Using XInclude for text inclusions
Annotating program listings
Line annotations
Line numbering
Callouts
Callouts on imported text
Callouts on graphics
Syntax highlighting
Chapter 27. Q and A sets
Q and A labeling
Q and A formatting
Q and A list of questions
Hiding the answers
Chunking Q and A
Chapter 28. Tables
Table width
Column widths
Cell spacing and cell padding
Row height
Cell alignment
Horizontal alignment
Vertical alignment
Cell rotation
Cell spanning
Horizontal spans
Vertical spans
Borders
Table border
Row borders
Column borders
Border styles
Background color
Cell background color
Row background color
Table styles in print output
table.properties attribute-set
informaltable.properties attribute-set
table.table.properties attribute-set
table.cell.properties template
table.cell.block.properties 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
Chapter 29. 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
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
Glossary
Index