3. Output Style Customizations
Prev Chapter 3. User's Reference manual Next

3. Output Style Customizations

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.

3.1. Customizing Existing Formats

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:

drivers/docbook-jadetex.dsssl

for PDF and PS formats outputs;

drivers/docbook-xhtml.xsl

for flat HTML output format;

drivers/docbook-xhtml-chunk.xsl

for chunked HTML output format.

Consult the documentation on how to customize XSL and DSSSL stylesheets if needed.

3.2. Creating a New Customization Layer

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:

  1. 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.

  2. 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="UTF-8"?>
<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.

Prev Up Next
2. Generating Final Documents Home 4. Revision Management