David Horton This document provides instructions for installing the TLDP XSL style sheets and using them to produce various output formats from DocBook XML source files. The TLDP-XSL package is a customization layer for the standard DocBook XSL style sheets. The customizations include things like automatic numbering for chapters and sections as well as controlling how documents are broken into multiple HTML pages. For additional information about these customizations, please refer to the comments within the XSL files in the html and fo directories of the tldp-xsl package. Copyright (c) 2003-2005 David Horton Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the file license.txt. This documentation is provided as-is with no warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. Use the concepts, examples and information at your own risk. The author(s) do not take any responsibility for damages that may arise from the use of this document. All copyrights are held by their respective owners, unless specifically noted otherwise. Use of a term in this document should not be regarded as affecting the validity of any trademark or service mark. Naming of particular products or brands should not be seen as endorsements. Installation is very straightforward and simply involves copying the TLDP-XSL style sheets into the appropriate directories of the DocBook XSL style sheet package. The following tasks should be completed prior to installation of the TLDP-XSL style sheets: Download Norman Walsh's docbook-xsl style sheet package and copy the contents of the package into an appropriate directory on the target system. The actual directory path is not critical, just make a note of where the files are placed. Download the latest version of the tldp-xsl package. Once the prerequisites are taken care of, installation is easy. Copy all of the files from the tldp-xsl package html directory into the html directory of Norman Walsh's style sheets. Copy the file from the tldp-xsl package fo directory into the fo directory of Norman Walsh's style sheets. Using the XSL style sheets to produce HTML output requires an XSLT processor. Producing other output types, like PDF, requires a Formatting Objects (FO) processor. These style sheets have been tested with xsltproc, the Saxon-6.5.2 XSLT processor and the Apache fop-0.20.5 formatting objects processor, but any processor that is compatible with the target system should work equally well. Processor installation is beyond the scope of this document. Please refer to the instructions included with the chosen product. There are several different XSL style sheets in the tldp-xsl package and each one is intended to address a particular formatting task. The style sheets and their intended uses are summarized below: fo/tldp-print.xsl works with a formatting objects (FO) processor to create PDF and other non-HTML formatted documents. This type of document is good to use when printed output is desired. html/tldp-single-page.xsl places all document output on a single HTML page. This works well for short, on-line documents like FAQ's or mini-HOWTO's. html/tldp-sections.xsl divides the document into sections with each section having a separate HTML page. This is good for producing HOWTO documents for on-line viewing. html/tldp-chapters.xsl divides the document into chapters, each having a separate HTML page. This style sheet can be used as an alternative to tldp-sections.xsl to provide better continuity in the document. the tldp-common.xsl file is intended to be used by other XSL style sheets and should not be called directly in an attempt to produce HTML output. The sections below give some examples of how to use the XSL style sheets to produce different types of output with various processors. Please be aware that file names and paths may be different on the target system and will need to be adjusted accordingly. This example shows the style sheets being used to create a single-page HTML document with xsltproc on a GNU/Linux platform: xsltproc -o faq.html ~/docbook-xsl/html/tldp-one-page.xsl faq.xml Here is an example using the style sheets with Instant Saxon on a Windows platform to create multiple-page HTML output with each section on its own HTML page: cd output_dir saxon c:\source_dir\howto.xml c:\docbook-xsl\html\tldp-sections.xsl It is also possible to create multiple-page HTML documents with each chapter on its own HTML page as show in this example: xsltproc ~/docbook-xsl/html/tldp-chapters.xsl ~/xml-files/howto.xml The following example uses the tldp-print.xsl style sheet with Apache FOP to create a .PDF document: fop -xml guide.xml -xsl ~/docbook-xsl/fo/tldp-print.xsl -pdf guide.pdf The tldp-print.xsl stylesheet and Apache FOP may also be used to produce formatted output in an on-screen window or send formatted output directly to a printer. Examples of this are shown below: fop -xml howto.xml -xsl ~/docbook-xsl/fo/tldp-print.xsl -awt fop -xml howto.xml -xsl ~/docbook-xsl/fo/tldp-print.xsl -print It is theoretically possible to produce other types of output, however the examples shown above are give the best results at this time. Check the Apache FOP home page to see which other output types are supported and what the current limitations are for those formats. HTML produced by the tldp-xsl package contains a link tag that refers to a cascading style sheet called style.css. To add some style to HTML output simply copy any valid CSS file with the name style.css into the directory that contains the HTML document. A sample style.css is included in the doc directory of this package and is used to style the HTML version of this howto. Browsers that do not support CSS should probably ignore the link with no ill effects. For information on CSS visit http://www.w3c.org/Style/CSS. Please send feedback concerning this document and the tldp-xsl style sheets to dhorton@NOSPAM.member.fsf.org