The Crash Course to DocBook

2.5. Introducing the Style Sheets

Note

This section is a bit outdated. It should describe the XSLT style sheets as well.

Stylesheets can tune the conversion in a way the resulting files have more clever names. Change the <book> and <chapter> tags in the above example as follows:

Example 2-2. The minimal DocBook file, with some attributes


<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN">
 
<book lang="en">
<!-- Please remark the "lang" attribute here -->
 
<bookinfo>
<title>Hello, world</title>
</bookinfo>
 
<chapter id="introduction">
<title>Hello, world</title>
 
<para>This is my first DocBook file.</para>
 
</chapter>
</book>

The text between <!-- and --> above is a comment; use it to attract the attention of someone reading the DocBook source. It will never get processed.

Now use the style sheet provided with the docbook-utils:


$ cp /usr/share/sgml/docbook/utils*/docbook-utils.dsl .
$ docbook2html -d docbook-utils.dsl#html myfile.docbook

Now the files should go to a HTML directory, and be named index.html and introduction.html, instead of having names like book1.htm. The main file will always be named index.html and the chapters like <chapter id="introduction"> will go to files named after the id attribute. This change has been accomplished through style sheet magic.

Note

Use #print instead of #html to specify the right part of the style sheet to use if you try them with some command like docbook2pdf instead of docbook2html.

In fact the style sheets are a very powerful tool. They enable you to get rid of problems like "I want it to look like this". If you come to such questions while writing a DocBook file, then it means that something is going wrong in your approach of the things.

If you get a look to the style sheet file named docbook-utils.dsl, you'll see that it is written in a cryptic language named DSSSL, that looks really like some LISP. This unfortunately means that some good programming knowledge is often required to tune the stylesheets.

More information on how to customize the stylesheets can be found on http://www.nwalsh.com/docbook/dsssl/doc/. More information on DSSSL can be obtained on http://www.jclark.com/dsssl/.