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.