Deriving Your Own Stylesheet

The best way to customize the stylesheets is to write your own “driver” file; this is a document which contains your local modifications to the stylesheet and then includes the stylesheet from the standard distribution by reference. This allows you to make local changes and extensions without modifying the distributed files, which makes upgrading to the next release much, much simpler.

The basic driver file looks like this:

<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
<!ENTITY dbstyle SYSTEM "docbook.dsl" CDATA DSSSL>
]>

<style-sheet>
<style-specification use="docbook">
<style-specification-body>

;; your stuff goes here...

</style-specification-body>
</style-specification>
<external-specification id="docbook" document="dbstyle">
</style-sheet>

Make sure that you specify, in the system identifier, the full path to the docbook.dsl file that you want to customize; for example, \docbook\print\docbook.dsl.

You can add your own definitions, or redefinitions, of stylesheet rules and parameters where

;; your stuff goes here...

The plain.dsl stylesheet in the docbook/print directory is a customization of the docbook.dsl print stylesheet. It turns off title page and TOC generation.

Changing the Localization

As distributed, the stylesheets use English for all generated text, but several other localization files are also provided. As of July 2001, the supported languages are: Afrikaans, Catalan, Chinese (Continental), Chinese (Traditional), Czech, Danish, Dutch, English, Estonian, Finnish, French, German, Greek, Hungarian, Indonesian, Italian, Japanese, Korean, Norwegian, Polish, Portuguese (Brazil), Portuguese, Romanian, Russian, Serbian, Slovak, Slovenian, Spanish, Swedish, and Turkish (if you can write a localization for another language, please do, and send it to me).

Switching localizations is achieved by writing a customization layer that references the proper localization file. The customization should look like this:

<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
<!ENTITY dbstyle PUBLIC "-//Norman Walsh//DOCUMENT DocBook Print Stylesheet//EN" CDATA DSSSL>
<!-- The path to the l10n file must be correct, of course, and should -->
<!-- point to the print/html directory as appropriate for the preceding -->
<!-- dbstyle -->
<!ENTITY l10n    SYSTEM "docbook/print/dbl1dege.dsl" CDATA DSSSL>
]>

<style-sheet>
<style-specification use="l10n docbook">
<style-specification-body>

;; Additional customization here, if desired

</style-specification-body>
</style-specification>

<external-specification id="docbook" document="dbstyle">
<external-specification id="l10n" document="l10n">

</style-sheet>

Where dbl1dege.dsl is the name of the localization file you wish to use (German in this example)..

A Single Stylesheet for Both Print and HTML

A DSSSL style-sheet consists of one or more style-specifications. This allows one to build a single stylesheet that can format with either the print or HTML backends.

All you need is a customization skeleton that looks like this:

<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
<!ENTITY % html "IGNORE">
<![%html;[
<!ENTITY % print "IGNORE">
<!ENTITY docbook.dsl PUBLIC "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN" CDATA dsssl>
]]>
<!ENTITY % print "INCLUDE">
<![%print;[
<!ENTITY docbook.dsl PUBLIC "-//Norman Walsh//DOCUMENT DocBook Print Stylesheet//EN" CDATA dsssl>
]]>
]>
<style-sheet>
<style-specification id="print" use="docbook">
<style-specification-body> 

;; customize the print stylesheet

</style-specification-body>
</style-specification>
<style-specification id="html" use="docbook">
<style-specification-body> 

;; customize the html stylesheet

</style-specification-body>
</style-specification>
<external-specification id="docbook" document="docbook.dsl">
</style-sheet>

If this is both.dsl, I can format my document using the print stylesheet by running

jade -t rtf -d both.dsl#print file.sgm

jade -t sgml -ihtml both.dsl#html file.sgm

An alternative method for doing this is simply to use marked sections in the stylesheet, like this:

<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
<!ENTITY % html "IGNORE">
<![%html;[
<!ENTITY % print "IGNORE">
<!ENTITY docbook.dsl PUBLIC "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN" CDATA dsssl>
]]>
<!ENTITY % print "INCLUDE">
<![%print;[
<!ENTITY docbook.dsl PUBLIC "-//Norman Walsh//DOCUMENT DocBook Print Stylesheet//EN" CDATA dsssl>
]]>
]>
<style-sheet>
<style-specification use="docbook">
<style-specification-body> 

;; common customization can go here

<![%print;[

;; customize the print stylesheet here

]]>

<![%html;[

;; customize the html stylesheet here

]]>

</style-specification-body>
</style-specification>
<external-specification id="docbook" document="docbook.dsl">
</style-sheet>

Customizing the Title Page

Titlepages are controlled by several variables:

The most common customization is probably setting %generate-element-titlepage% to true and changing the list of elements in element-titlepage-recto-elements and element-titlepage-verso-elements

There are a few other functions that you may wish to change:

Using the Stylesheets with XML

This is just a placeholder. This needs to be written. Basically, you just need to use catalog files to make sure that the XML instances and the stylesheets get parsed with the correct declarations.