Next / Previous / Contents / TCC Help System / NM Tech homepage

Table of Contents

1. Introduction
1.1. Bob Stayton's DocBook XSL: The complete guide
1.2. How to get this publication
2. Skills you will need
3. What is a customization layer?
4. Overall structure of the local customization layer
5. Title page customization: XSLT that builds XSLT
6. tcc_html.xsl: HTML customization layer
6.1. HTML general page layout
6.2. HTML title page and table of contents
6.3. HTML headers and footers
6.3.1. The header.navigation template
6.3.2. The tcc.top.nav.bar template
6.3.3. The footer.navigation template
6.3.4. The tcc.bot.links template
6.3.5. The tcc.colophon template
6.3.6. The author.colophon.mode template
6.4. HTML section and subsection headings
6.5. HTML specific element customizations
6.5.1. The inline.italicsansseq template
6.5.2. The inline.smallcapsseq template
6.5.3. Verbatim elements: programlisting, screen, and literallayout
6.5.4. application
6.5.5. Emphasis with boldface
6.5.6. callout graphics
6.5.7. firstterm
6.5.8. guibutton, guiicon, guilabel, and guimenu
6.5.9. The keysym element
6.6. Epilogue for the HTML stylesheet
7. html-titlepage.xml: HTML title page template
8. tcc_fo.xsl: PDF customization layer
8.1. General page layout
8.2. Templates for title elements
8.3. PDF headers and footers
8.3.1. Other header/footer options to consider
8.4. PDF section and subsection headings
8.5. PDF inline element customizations
8.5.1. The inline.italicsansseq template
8.5.2. The inline.smallcaps template
8.5.3. application and the gui* group
8.5.4. Bold emphasis
8.5.5. Callouts
8.5.6. firstterm
8.5.7. keysym
8.5.8. xref: Page cross-reference format
8.6. PDF block element customizations
8.6.1. Admonitions: caution, important, note, tip, and warning
8.6.2. programlisting and other verbatim elements
8.6.3. variablelist: Variable list entry term
8.7. PDF epilogue
9. fo-titlepage.xml: PDF title page template

1. Introduction

DocBook is a generalized framework for writing documentation using XML. Here at the New Mexico Tech Computer Center (TCC), we use DocBook extensively for external and internal documentation. Among the many advantages of this system is that a single source document can be translated mechanically to both HTML and PDF representations.

This document contains all the files used for local customization, in “lightweight literate programming” format. For more information, see the author's Lightweight literate programming page.

The local DocBook toolchain consists of these components:

  • Norman Walsh's DocBook XSL Stylesheets provide a generic styling of DocBook that can be customized with local style conventions. These stylesheets consist of XSLT scripts. For more information about XSLT, see XSL Transformations (XSLT) Version 1.0.

    These style sheets can be downloaded from the SourceForge repository.

  • The xsltproc package implements the XSLT language. Production of the HTML output from a DocBook document needs only XSLT.

  • The xep processor is necessary to produce the printable, PDF (Adobe Page Description Format) form of a DocBook document. This transformation starts by using xsltproc to transform the original DocBook document into XSL, also known as XSL-FO (for Formatting Objects). The resulting .fo file is input to xep, which produces the PDF output file.

    For more information on XSL, see the standard: Extensible Stylesheet Language (XSL) Version 1.0.

1.1. Bob Stayton's DocBook XSL: The complete guide

Without customization, the stock DocBook XSL Stylesheets produce a pretty bland, generic output style. This document describes the TCC's local customization layers, built on top of the DocBook XSL Stylesheets, that give our documents their local style.

Documentation for the DocBook XSL Stylesheets is rather skeletal. Fortunately, there is an excellent book that describes the customization process in detail:

Stayton, Bob. DocBook XSL: The complete guide. Third edition, March 2005, ISBN 0-9741521-2-9.

This book will be referred to throughout this document as “Stayton.”

Another good resource is the DocBook XSL Stylesheet Wiki.

1.2. How to get this publication

This publication is available in Web form and also as a PDF document. Please forward any comments to tcc-doc@nmt.edu.