# GNOME Documentation XSLT Manual

The GNOME Documentation XSLT stylesheets were created to provide fast DocBook to HTML conversion for real-time document viewing in GNOME's help browser, Yelp.

2004
Shaun McCance
GNOME Documentation Project
Shaun
McCance
GNOME Documentation Project
shaunm@gnome.org
Brent
Smith
GNOME Documentation Project
gnome@nextreality.net
0.1
2004-03-31
0.2
2006-02-11

## Introduction

The GNOME XSLT Stylesheets are used to generate HTML from DocBook files.

Some of the goals of these stylesheets are:

- To provide real-time translation of DocBook into HTML. The GNOME Help Browser, Yelp, uses these stylesheets to format help documents.

- To provide a customized look and feel for GNOME's documentation.

- To provide translation support for GNOME documentation.

## Using the Stylesheets

To use the stylesheets you should be familiar with the xsltproc application. The first argument is the location of the `db2html.xsl` stylesheet. The second argument is the top-level docbook file for which to generate the HTML.

### Generating HTML from a DocBook file

    $ xsltproc /usr/share/xml/gnome/xslt/docbook/html/db2html.xsl <docbook file>

For more information on xsltproc and the libxslt libraries, see http://xmlsoft.org/.

### XInclude Processing

If you make use of XInclude to include other files in your document, then you must use the `--xinclude` parameter to generate the complete DocBook file before processing it with the `db2html.xsl` stylesheet(s).

## Specifying Parameters

There are a number of parameters available in the stylesheets which you can set to customize the generated html. An exhaustive list is available in the following sections, but we will go over a few of the more commonly used ones in this section.

To specify a parameter to the stylesheets, use the `--stringparam` option of the xsltproc application.

db.chunk.chunk_top

  Set this parameter to `1` if you want the stylesheets to chunk Chunking refers to creating a separate output file for an element. For example, if there are three `<sect1>` elements within a document, (with no subsections) then there will be three files generated for each element. Incidentally, the name of the files will be the same as the element's `id` attribute. the top level element (`<article>` or `<book>`) into a file called `index.xhtml`.

db.chunk.max_depth

  Specifies the maximum depth of chunked elements specified in `db.chunk.chunks` parameter.

db.chunk.extension

  Set this parameter to `the extension` you would like for the chunked output files.

### Example of specifying stylesheet parameters

    $ xsltproc \
       --stringparam db.chunk.chunk_top 1        \
       --stringparam db.chunk.max_depth 1        \
       --stringparam db.chunk.extension '.html'  \
       /usr/share/xml/gnome/xslt/docbook/html/db2html.xsl \
       <path to docbook file>

will chunk the top level element, chunk to a maximum depth of 1 and chunk the title page.

## Limitations

Currently, the stylesheets require that there be an `id` attribute on each chunked element.

## Stylesheet Reference