# 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 . You can use it to convert documents with:

    bash$ xmlto html mydoc.xml
    bash$ xmlto txt mydoc.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: , for more information about XSLT read: .

## 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).

- The Document Type Definition file which matches the DOCTYPE of your document (this is a plain text file).

- A processor to do the actual work.

### 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

The
Document Style Semantics and Specification Language tells Jade (see ) 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.

#### 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`.

### 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

  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.

### System Setup for DSSSL Transformations

1. 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 .

2. Download the DSSSL and DTD files and copy them into your working directory. You can find an example of how to do this in and .

### 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:

    bash$ jade -t xml -i html \
    	-d /usr/local/sgml/dsssl/docbook/html/ldp.dsl#html \
    	/usr/lib/sgml/declaration/xml.dcl HOWTO.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.

#### 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.

## 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 can be installed on most systems.

### 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 .

### 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 .

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: is a book formatted with the standard tools; is one using personalized DSL and CSS files. Soft tones and special effects, for instance in buttons, were used to achieve maximum effect.

## XSL

There are alternatives to DSSSL and Jade/OpenJade.

When working with DocBook XML, the LDP offers a series of XSL 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. 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:

1. `tldp-html.xsl` - style sheet called to generate a single file.

2. `tldp-html-chunk.xsl` In XSL terminology, the process of generating multiple files is referred to as "chunking". - style sheet called to generate multiple files based on chapter, section and appendix elements.

3. `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.

4. `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 . 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.

### Changing CSS Files

If you want your HTML files to use a specific CSS stylesheet, you will need to edit `tldp-html-common.xsl`. Look for a line that ressembles `<xsl:param name="html.stylesheet" select="'style.css'"/>`.

Replace `style.css` with the name of the CSS file you would like to use.

# DocBook DTD

The DocBook DTD defines the structure of a DocBook document. It contains rules about how the elements may be used; and what the elements ought to be describing. For example: it is the DocBook DTD which states all `warning`s are to warn the reader (this is the definition of the element); and may not contain plain text (this is the content model--and the bit which forces you to wrap your warning text in a `para` or perhaps a list).

## Versions

It is important that you download the version(s) that match your document. You may want to configure your system now to deal with all DocBook DTDs if you are going to be editing older LDP documents. If you are a new author, you only need the first one listed: XML DTD for DocBook version 4.2.

The XML DTD is available from http://www.oasis-open.org/xml/4.2/. The LDP prefers this version of the DocBook DTD.

If you are going to be working with SGML versions of DocBook you will need one (or both) of: http://www.oasis-open.org/docbook/sgml/4.1/docbk41.zip or http://www.oasis-open.org/docbook/sgml/3.1/docbk31.zip

## Installing DocBook Document Type Definitions

Create a base directory to store everything such as `/opt/local/sgml/`. Copy the DTDs into a sub-directory named `dtd`.

## Do not edit DTD files

The DocBook standard is described in these files. If you change these files, you are no longer working with DocBook.

# Formatting Documents

## Inserting a summary on the initial articles page

A feature that might be valuable in some cases is the insertion of the summary on the initial page of an article. DocBook articles do not include it as a standard feature.

To enable this, it is necessary to modify the style sheet file.

### Style sheet to insert summaries in articles

    &dsl-example;

## Inserting indexes automatically

Although DocBook has markups for the composition of them, indexes are not generated automatically. The `collateindex.pl` command allows indexes to be generated from the source DocBook for inclusion into the finished/transformed document.

1. Process the document with jade using the style to HTML with the option `-V html-index`.

       bash$ jade -t sgml \
       	-d html/docbook.dsl -V html-index document.sgml

2. Generate the `index.sgml` file with `collateindex.pl`.

       bash$  perl collateindex.pl \
       	-o index.sgml HTML.index

For the above example to work, it is necessary to define an external entity by calling the file `index.sgml`.

### Configuring an external entity to include the index

    !DOCTYPE article PUBLIC "-//OASIS//DTD
    DocBook V3.1//EN" [

    <!-- Insertion of the index --> <!entity index SYSTEM
    "index.sgml"> ]

See also for information on how to insert necessary information on the text.

### Odd behavior generating indexes for print versions

Remember that if you're trying to get Tables of Contents or Indexes on PS or PDF output you'll need to run jadetex or pdfjadetex at least three times. This is required by TeX but not by DocBook or related applications.