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:
bash$xmlto htmlmydoc.xmlbash$xmlto txtmydoc.xml
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 4.1, “DSSSL”, for more information about XSLT read: Section 4.3, “XSL”.
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 4.1.1, “The Style Sheets”
The Document Type Definition file which matches the DOCTYPE of your document (this is a plain text file). Section 5, “DocBook DTD”
A processor to do the actual work. Section 4.1.2, “DSSSL Processors”
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 4.1.2, “DSSSL Processors”) 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.
Example B.5. “Installing” DSSSL style sheets
Create a base directory to store everything such as /usr/share/sgml/. Copy the DSSSL
style sheets into a sub-directory named
dsssl.
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
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.
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.
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, “Setting the SGML_CATALOG_FILES and XML_CATALOG_FILES Environmental Variables”.
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, ““Installing” DSSSL style sheets” and Example B.7, ““Installing” DocBook Document Type Definitions”.
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
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:
bash$jade -t xml -i html \ -d /usr/local/sgml/dsssl/docbook/html/ldp.dsl#html \ /usr/lib/sgml/declaration/xml.dclHOWTO.xml
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”.
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.
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 Not a function name errors.
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, Templates.
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.
There are alternatives to DSSSL and Jade/OpenJade.
When working with DocBook XML, the LDP offers a series of XSL[2] 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[3] - 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 -oHOWTO.html/usr/local/sgml/stylesheets/tldp-html.xslHOWTO.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.xslHOWTO.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.
[2] In truth, "XSL" is actually comprised of three components: the XSLT transformation language, the XPath expression language (used by XSLT), and XSL Formatting Objects (FO) that are used for describing a page. The style sheets are actually written in XSLT and generate either HTML or (for print output) FO. The FO file is then run through a FO processor to create the actual print (PDF or PostScript) output. See the W3C web site for more information.
[3] In XSL terminology, the process of generating multiple files is referred to as "chunking".