XML.com

DocBook for Eclipse: Reusing DocBook's Stylesheets
by Jirka Kosek | Pages: 1, 2

Extending DocBook XSL stylesheets

As the Eclipse help is based on HTML, we can reuse existing stylesheets that generate multiple HTML files from DocBook XML source. However, we need to extend these stylesheets to generate the table of contents file and the manifest file.

The first thing that has to be done when reusing an existing stylesheet is to import it. The first XSLT instruction in our stylesheet thus has to be

<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl"/>

Of course you can change the URL of the stylesheet to point to your local copy of the DocBook XSL stylesheet or better you can use catalog files for doing such resource redirection.

Next we must invoke the original stylesheet code to get HTML files from the XML source and then invoke our code to generate the table of contents and manifest files.

<xsl:template match="/">
  <!-- Call original code from the imported stylesheet -->
  <xsl:apply-imports/>

  <!-- Call custom templates for the ToC and the manifest -->
  <xsl:call-template name="etoc"/>
  <xsl:call-template name="plugin.xml"/>
</xsl:template>

We start with the second template, which generates the manifest file, as it is very simple and demonstrates a cool template which is a part of the DocBook XSL stylesheets.

The plugin.xml template must generate a simple manifest file and save it into the plugin.xml file. Generating multiple output files with XSLT is not standardized in XSLT 1.0, and each XSLT processor utilizes its own extension instruction to do it (many of processors also support EXSLT instruction for doing this). To isolate the stylesheet developer from processor differences, the DocBook XSLT stylesheets define a write.chunk template which will select and use appropriate processor-dependent instruction for you. By using parameters you can feed the template with important information like the name of the generated file or its content.

<xsl:template name="plugin.xml">
  <xsl:call-template name="write.chunk">
    <xsl:with-param name="filename" select="'plugin.xml'"/>
    <xsl:with-param name="method" select="'xml'"/>
    <xsl:with-param name="encoding" select="'utf-8'"/>
    <xsl:with-param name="indent" select="'yes'"/>
    <xsl:with-param name="content">
      <plugin name="{$eclipse.plugin.name}"
              id="{$eclipse.plugin.id}"
              version="1.0"
              provider-name="{$eclipse.plugin.provider}">
        <extension point="org.eclipse.help.toc">
          <toc file="toc.xml" primary="true"/>
        </extension>
      </plugin>
    </xsl:with-param>
  </xsl:call-template>
</xsl:template>

As you can see, the global parameters are used to allow the stylesheet user to easily customize things like plugin name or id.

The most important part of the stylesheet is the etoc template, responsible for generating the the table of contents file for the Eclipse platform help system. We will use write.chunk template introduced before to create a separate toc.xml file. The table of contents file must contain the hierarchy of the topic elements which corresponds to structure of our document. This can be generated very easily using XSLT. You must create a template which will process all DocBook container elements like chapter, appendix, and section; for each such element it will add the corresponding topic element to the output.

Each topic should be provided with its name and name of the HTML file which holds its contents. The DocBook XSLT stylesheets already contain code for getting this information. If you apply templates in title.markup mode to some node, you will get its title. Similarly you can use the named template href.target.with.base.dir to get the filename which contains output of specific node in your source DocBook document.

If you combine all the templates together you will get this, still quite simple, stylesheet with which you can turn any valid DocBook instance into Eclipse platform help.

<?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                version="1.0">

<!-- Import of the original stylesheet which "just" creates 
     a bunch of HTML files from any valid DocBook instance -->
<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl"/>

<!-- You must plug-in your custom templates here --> 
<xsl:template match="/">
  <!-- Call original code from the imported stylesheet -->
  <xsl:apply-imports/>

  <!-- Call custom templates for the ToC and the manifest -->
  <xsl:call-template name="etoc"/>
  <xsl:call-template name="plugin.xml"/>
</xsl:template>

<!-- Template for creating auxiliary ToC file -->
<xsl:template name="etoc">
  <xsl:call-template name="write.chunk">
    <xsl:with-param name="filename" select="'toc.xml'"/>
    <xsl:with-param name="method" select="'xml'"/>
    <xsl:with-param name="encoding" select="'utf-8'"/>
    <xsl:with-param name="indent" select="'yes'"/>
    <xsl:with-param name="content">

      <!-- Get the title of the root element -->
      <xsl:variable name="title">
        <xsl:apply-templates select="/*" mode="title.markup"/>
      </xsl:variable>
    
      <!-- Get HTML filename for the root element -->
      <xsl:variable name="href">
        <xsl:call-template name="href.target.with.base.dir">
          <xsl:with-param name="object" select="/*"/>
        </xsl:call-template>
      </xsl:variable>
      
      <!-- Create root element of ToC file -->
      <toc label="{$title}" topic="{$href}">
        <!-- Get ToC for all children of the root element -->
        <xsl:apply-templates select="/*/*" mode="etoc"/>
      </toc>
      
    </xsl:with-param>
  </xsl:call-template>
</xsl:template>

<!-- Template which converts all DocBook containers into 
     one entry in the ToC file -->
<xsl:template match="book|part|reference|preface|chapter|
                     bibliography|appendix|article|glossary|
                     section|sect1|sect2|sect3|sect4|sect5|
                     refentry|colophon|bibliodiv|index" 
              mode="etoc">
  <!-- Get the title of the current element -->
  <xsl:variable name="title">
    <xsl:apply-templates select="." mode="title.markup"/>
  </xsl:variable>

  <!-- Get HTML filename for the current element -->
  <xsl:variable name="href">
    <xsl:call-template name="href.target.with.base.dir"/>
  </xsl:variable>

  <!-- Create ToC entry for the current node and process its 
       container-type children further -->
  <topic label="{$title}" href="{$href}">
    <xsl:apply-templates select="part|reference|preface|chapter|
                                 bibliography|appendix|article|
                                 glossary|section|sect1|sect2|
                                 sect3|sect4|sect5|refentry|
                                 colophon|bibliodiv|index" 
                         mode="etoc"/>
  </topic>

</xsl:template>

<!-- Default processing in the etoc mode is no processing -->
<xsl:template match="text()" mode="etoc"/>

<!-- Template for generating the manifest file -->
<xsl:template name="plugin.xml">
  <xsl:call-template name="write.chunk">
    <xsl:with-param name="filename" select="'plugin.xml'"/>
    <xsl:with-param name="method" select="'xml'"/>
    <xsl:with-param name="encoding" select="'utf-8'"/>
    <xsl:with-param name="indent" select="'yes'"/>
    <xsl:with-param name="content">
      <plugin name="{$eclipse.plugin.name}"
              id="{$eclipse.plugin.id}"
              version="1.0"
              provider-name="{$eclipse.plugin.provider}">
        <extension point="org.eclipse.help.toc">
          <toc file="toc.xml" primary="true"/>
        </extension>
      </plugin>
    </xsl:with-param>
  </xsl:call-template>
</xsl:template>

<!-- Customization parameters for the manifest file -->
<xsl:param name="eclipse.plugin.name">DocBook Online Help Sample</xsl:param>
<xsl:param name="eclipse.plugin.id">com.example.help</xsl:param>
<xsl:param name="eclipse.plugin.provider">Example provider</xsl:param>

</xsl:stylesheet>

More customizations

Now that you have working solution for transforming DocBook to Eclipse platform help, you can start fiddling with the appearance of the output. There are a lot of documented parameters which control the presentation and shape of the HTML output. It's common to create a custom CSS stylesheet for changing the presentation of the generated HTML and to set parameters in such a way that generated topics are as small as possible. You can achieve this by adding following parameters into your stylesheet:

<xsl:param name="html.stylesheet">eclipse.css</xsl:param>
<xsl:param name="chunk.first.sections" select="1"/>
<xsl:param name="chunk.section.depth" select="3"/>

Many other useful tips for customizing the DocBook XSLT stylesheets are described in the book DocBook XSL: The Complete Guide from Bob Stayton.

Screen shot of large DocBook document displayed inside the Eclipse help system.
Figure 2. Large DocBook document displayed inside the Eclipse help system.

Conclusion

Software documentation is an area where you can very effectively use XML and XSLT to do multichannel publishing. If you stick to using a well-known and standardized vocabulary like DocBook, you can benefit from usage of existing stylesheets and other conversion tools. If you want to plug your DocBook documentation into some new help format, you can quite easily hack existing stylesheets to generate a new output format. The method for creating output for the Eclipse platform help described in this article can be used for almost any HTML based online help system.

Extending DocBook XSL stylesheets

More customizations

Conclusion

Related links

Recommended for You

About O'Reilly

Community

Partner Sites

Shop O'Reilly