The Modular DocBook Stylesheets
PrevCustomizing the StylesheetsNext

Table of Contents
Writing Your Own Driver
Changing the Localization
A Single Stylesheet for Both Print and HTML

Writing Your Own Driver

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.

NOTE

The next stylesheet release will probably use public identifiers to locate the stylesheets, which will simplify this problem a bit (at the cost, naturally, of a little more complexity elsewhere; sigh).

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

;; your stuff goes here...
occurs in the example above.

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 German and Russian localization files are also provided[1] (if you can write a localization for another language, please do, and send it to me).

[1] The non-English localization layers are sometimes a little out-of-date with respect to generated text. If Jade reports errors that %gentext-something is undefined, that's the problem. Hopefully the required text is fairly obvious, but if not, drop me a note and I'll explain it. In any case, if you add appropriate text, please send it to me so I can update the distributed localizations.

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 SYSTEM "docbook.dsl" CDATA DSSSL>
<!ENTITY l10n    SYSTEM "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 SYSTEM ".../html/docbook.dsl" CDATA dsssl>
]]>
<!ENTITY % print "INCLUDE">
<![%print;[
<!ENTITY docbook.dsl SYSTEM ".../print/docbook.dsl" 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
and using the HTML stylesheet by running
jade -t sgml -ihtml both.dsl#html file.sgm
which is kindof neat. (I've built some additional machinery on top of this to make the selection automatic from within Adept and a shell script that I use.)


PrevHomeNext
Installation and Setup The Print Stylesheet