With Borges it is very easy to control the way final
documents are formatted thanks to DocBook
customization features.
Moreover it is easy to create new customization layers so that each
manual can have its own design.
As we already seen in Section 1.1.3, “conf/manual-default.xml”, the customization
layers for all output formats are located in
drivers/
directory. You just need to open the
stylesheet corresponding to the format you want to change with your
text editor:
Consult the documentation on how to customize XSL and DSSSL stylesheets if needed.
Having one customization layer per output format might not be
enough for some special needs. Let's imagine that there is a manual
you want to publish in both Europe and in the United States. Therefore
you need two different paper formats: A4
and Letter
. This is done in two simple
steps:
Create a new customization layer
This customization layer will be placed on top of Borges print customization layer, resulting in the following layers:
![]() |
Our new customization layer
(drivers/docbook-jadetex-Letter.dssssl
)
would look like:
<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [<!ENTITY docbook-jadetex.dsssl SYSTEM "docbook-jadetex.dsssl" CDATA DSSSL > ]> <style-sheet> <style-specification id="print" use="docbook-jadetex"> <style-specification-body> ;;What size paper do you need? A4, A5, USletter or USlandscape? (define %paper-type% "USletter") </style-specification-body> </style-specification> <external-specification id="docbook-jadetex" document="docbook-jadetex.dsssl"> </style-sheet>
Now that the customization layer is ready we just need to direct the system to use it in the second step.
The default Borges print stylesheet uses
A4
paper format. We then need to create a new
manual that will use the “Letter” customization
layer we just created. This is done in the super document
configuration file, for example
manuals/Install-guide/conf.xml
:
<?xml version="1.0" encoding="ISO-8859-1"?> <configuration> <stylesheet> <dssslprint>../../drivers/docbook-jadetex.dsssl</dssslprint> <xslxhtmlflat>../../drivers/docbook-xhtml.xsl</xslxhtmlflat> <xslxhtmlchunk>../../drivers/docbook-xhtml-chunk.xsl</xslxhtmlchunk> </stylesheet> <manuals> <manual id="Install-guide-A4"> <lang>en</lang> <format>pdf</format> </manual> <manual id="Install-guide-Letter"> <lang>en</lang> <format>pdf</format> <stylesheet> <dssslprint>../../drivers/docbook-jadetex-Letter.dsssl</dssslprint> </stylesheet> </manual> </manuals> </configuration>
In this file, the first stylesheet
element informs the system that we want to use the Borges
stylesheets per default. Therefore, the
Install-guide-A4
manual will use
docbook-jadetex.dsssl
with
A4
paper format. However for manual
Install-guide-Letter
we specify that we want
to use our customization layer
docbook-jadetex-Letter.dsssl
. The other
formats (HTML) will still use the default stylesheets as we did
not redefine them.
Once this is done, you can use the Section 2.2, “Generating Multiple
Documents at One Time” feature to generate, at the same time, the two
different books Install-guide-A4.pdf
and
Install-guide-Letter.pdf
respectively in
A4
and Letter
paper
formats.