B.4. Transformations
 | TLDP will convert your document | |
|---|---|---|
This section is about how to transform documents from DocBook to other formats. If you do not need to transform documents for your own web site, or to proof read the content, please skip this section. If you would like to transform your documents for proofreading purposes, please use the XML to HTML on-line converter. You will need to upload your XML file(s) to a web site. Then simply drop the URL into the form and click the submit button. Your document will be magically transformed into a beautiful (and legible) HTML document. External files are supported. You may use either absolute or relative URIs. Another easy-to-use package is xmlto. It is a front-end for xsltproc. It is available as a RedHat, Debian (etc) package or can be downloaded from http://cyberelk.net/tim/xmlto/. You can use it to convert documents with:
You do not ever need to transform documents before submitting to the LDP. The LDP volunteers have a system which transforms your DocBook file into HTML, PDF and plain text formats. There, you've been warned. |
Still here? Great! Transformations are a pretty basic requirement to get what you've written from a messy tag-soup into something that can be read. This section will help you get your system set up and ready to transform your latest document into other formats. This is very useful is you want to see your document before you release it to the world.
There are currently two ways to transform your document: Document Style Semantics and Specification Language (DSSSL); and XML Style sheets (XSLT). Although the LDP web site uses DSSSL to convert documents you may use XSLT if you want. You only need to choose one of these methods. For more information about DSSSL read: Section B.4.1, for more information about XSLT read: Section B.4.3.
B.4.1. DSSSL
There are three basic requirements to transform a document using DSSSL:
The Document Style and Semantics Specification Language files (these are plain text files). Section B.4.1.1
The Document Type Definition file which matches the DOCTYPE of your document (this is a plain text file). Section B.5
A processor to do the actual work. Section B.4.1.2
B.4.1.1. The Style Sheets
There are two versions of the Document Style Semantics and Specification Language used by the LDP to transform documents from your raw DocBook files into other formats (which are then published on the Web). The LDP version of the style sheets requires the Norman Walsh version--which basically means if you're using DSSSL the Norman Walsh version can be considered a requirement for system setup.
Norman Walsh DSSSL http://docbook.sourceforge.net/projects/dsssl/. The Document Style Semantics and Specification Language tells Jade (see Section B.4.1.2) how to render a DocBook document into print or on-line form. The DSSSL is what converts a title tag into an <h1> HTML tag, or to 14 point bold Times Roman for RTF, for example. Documentation for DSSSL is located at the same site. Note that modifying the DSSSL doesn't modify DocBook itself. It merely changes the way the rendered text looks. The LDP uses a modified DSSSL (see below).
LDP DSSSL http://www.tldp.org/authors/tools/ldp.dsl. The LDP DSSSL requires the Norman Walsh version (see above) but is a slightly modified DSSSL to provide things like a table of contents.
B.4.1.2. DSSSL Processors
There are two versions of the Jade processor: the original version by James Clark; and an open-source version of approximately the same program, OpenJade. You only need one of these programs. It should be installed after the DTD and DSSSL have been "installed."
DSSSL Transformation Tools
- Jade
ftp://ftp.jclark.com/pub/jade/
Currently, the latest version of the package is jade-1.2.1.tar.gz.
Jade is the front-end processor for SGML and XML. It uses the DSSSL and DocBook DTD to perform the verification and rendering from SGML and XML into the target format.
- OpenJade
http://openjade.sourceforge.net/
An extension of Jade written by the DSSSL community. Some applications require jade, but are being updated to support either software package.
B.4.1.3. System Setup for DSSSL Transformations
Tell your system where to find the SGML_CATALOG_FILES (yes, even if you are using XML). You can find an example of how to do this in Example B-1.
Download the DSSSL and DTD files and copy them into your working directory. You can find an example of how to do this in Example B-5 and Example B-7.
B.4.1.4. Transformations with DSSSL
Once your system is configured (see the previous section), you should be able to start using jade to transform your files from XML to XHTML.
To create individual HTML files, point jade at the correct DSL (style sheet). The following example uses the LDP style sheet.
bash$ jade -t xml -i html \ -d /usr/local/sgml/dsssl/docbook/html/ldp.dsl#html \ HOWTO.xml |
If you would like to produce a single-file HTML page, add the -V nochunks parameter. You can specify the name of the final HTML file by appending the command with > output.html.
bash$ jade -t xml -i html -V nochunks \ -d /usr/local/sgml/dsssl/stylesheets/ldp.dsl#html \ HOWTO.sgml > output.html |
 | Not a function name errors | |
|---|---|---|
If you get an error about "is not a function name", you will need to add a pointer to xml.dcl. It has to be listed immediately before the pointer to your XML document. Try one of the following locations: /usr/lib/sgml/declaration/xml.dcl, or /usr/share/sgml/declaration/xml.dcl. Use locate to find the file if it is not in either of those two places. The modified command would be as follows:
|
If you would like to create print-friendly files instead of HTML files, simply change the style sheet that you are using. In the file name above, note "html/ldp.dsl" at the end. Change this to "print/docbook.dsl", or if you want XHTML output, instead of HTML, change the file name to "xhtml/docbook.dsl".
B.4.1.4.1. Changing CSS Files
If you want your HTML files to use a specific CSS stylesheet, you will need to edit ldp.dsl. Immediately after ;; End of $verbatim-display$ redefinition add the following lines:
(define %stylesheet-type% ;; The type of the stylesheet to use "text/css") (define %stylesheet% ;; Name of the css stylesheet to use, use value #f if you don't want to ;; use css stylesheets "base.css") |
Replace base.css with the name of the CSS file you would like to use.
B.4.2. The docbook-utils Package
The docbook-utils provide commands like db2html, db2pdf and db2ps, based on the jw scripts, that is a front-end to Jade. These tools ease the everyday management of documentation and add comfortable features.
The package, originally created by RedHat and available from http://sources.redhat.com/docbook-tools/ can be installed on most systems.
Example B-6. Example creating HTML output
After validating your document, simply issue the command db2html mydoc.xml to create (a) HTML file(s). You can also use the docbook-utils as validation tools. Remember: when errors occur, always start by solving only the first problem. The rest of the problems may be fixed when you fix the first error.
If you get errors about a function name, please read .
B.4.2.1. Using CSS and DSL for pretty output
You can define your own additional DSL instructions, which can include a pointer to a personalized CSS file. Sample DSL and CSS files are provided in Appendix A.
The sample DSL file will create a table of contents, and have all HTML files start with the prefix intro2linux- and end with a suffix of .html. The %stylesheet% variable points to the CSS file which should be called by your HTML file.
To use a specific DSL style sheet the following command should be used:
db2html -d mystyle.dsl mydoc.xml
You can compare the result here: http://tille.xalasys.com/training/unix/ is a book formatted with the standard tools; http://tille.xalasys.com/training/tldp/ is one using personalized DSL and CSS files. Soft tones and special effects, for instance in buttons, were used to achieve maximum effect.
B.4.3. XSL
There are alternatives to DSSSL and Jade/OpenJade.
When working with DocBook XML, the LDP offers a series of XSL[1] style sheets to process documents into HTML. These style sheets create output files using the XML tool set that are similar to those produced by the SGML tools using ldp.dsl.
The major difference between using ldp.dsl and the XSL style sheets is the way that the generation of multiple files is handled, such as the creation of a separate file for each chapter, section and appendix. With the SGML tools, such as jade or openjade, the tool itself was responsible for generating the separate files. Because of this, only a single file, ldp.dsl was necessary as a customization layer for the standard DocBook DSSSL style sheets.
With the DocBook XSL style sheets, generation of multiple files is controlled by the style sheet. If you want to generate a single file, you call one style sheet. If you want to generate multiple files, you call a different style sheet. For that reason the LDP XSL style sheet distribution is comprised of four files:
tldp-html.xsl - style sheet called to generate a single file.
tldp-html-chunk.xsl[2] - style sheet called to generate multiple files based on chapter, section and appendix elements.
tldp-html-common.xsl - style sheet containing the actual XSLT transformations. It is called by the other two HTML style sheets and is never directly called.
tldp-print.xsl - style sheet for generation of XSL Formatting Objects for print output.
You can find the latest copy of the files at http://my.core.com/~dhorton/docbook/tldp-xsl/. The package includes installation instructions which are duplicated at http://my.core.com/~dhorton/docbook/tldp-xsl/doc/tldp-xsl-howto.html. The short version of the install instructions is as follows: Download and unzip the latest package from the web site. Take the files from the html directory of TLDP-XSL and put them in the html directory of Norman Walsh's stylesheets. Take the file from the TLDP-XSL fo directory and put it in the Norman Walsh fo directory.
Once you have installed these files you can use xsltproc to generate HTML files from your XML documents. To transform your XML file(s) into a single-page HTML document use the following command:
bash$ xsltproc -o HOWTO.html /usr/local/sgml/stylesheets/tldp-html.xsl HOWTO.xml |
To generate a set of linked HTML pages, with a separate page for each chapter, sect1 or appendix, use the following command:
bash$ xsltproc /usr/share/sgml/stylesheets/tldp-html-chunk.xsl HOWTO.xml |
Note that you never directly call the style sheet tldp-html-common.xsl. It is called by both of the other two style sheets.