Documentation of the customisation of the WebHelp toolchain

Reason for WebHelp Customisations

ChristianK applied quite a few customisations to the Docbook 'WebHelp' toolchain to achieve the HTML output we prefer for the upcoming OpenPetra Application Help (cf. Application Help Content Management and Delivery). This wiki page documents the DocBook WebHelp toolchain and the customisations ChristianK applied.

Toolchain Components

DocBook XLS-NS (WebHelp)

Initially, ChristianK used the latest official release of the DocBook XLS-NS files, 1.76.1, for the production of the WebHelp output. ChristianK couldn't achieve several things with this version and contacted the authors of WebHelp for advice. They provided many useful tips, but also made interim builds of DocBook WebHelp to cater for the things we wanted to achieve. Thus, ChristianK used interim builds of DocBook WebHelp for the latest results of our application help demo. The last interim build ChristianK used was Rev. r9195 (by dcramer, 2012-01-14 22:21:17 +0000 [Sat, 14 Jan 2012]). The interim builds can be downloaded from here: http://50.56.245.89/

Apache Ant

WebHelp depends on Apache Ant. The version ChristianK used was 1.8.0. There were newer versions out at that time (1.8.1 and 1.8.2), but those didn't include some libraries anymore on which WebHelp depends, so ChristianK used 1.8.0, which still contains those libaries. WebHelp might be able to deal with a newer version of Ant in an upcoming version.

Saxon

WebHelp depends on Saxon. The version ChristianK used was 6.5.5, which is the version that is recommeded in the WebHelp documentation.

Customisation Setup

On our development server 'jonah' the following directory exists:

C:\OpenPetra_SingleSourcePublishing\WebHelp processing stack (separate of Calenco!)\CURRENT\webhelp

In this directory the extracted contents of Rev. r9195 of DocBook XML-NS can be found. Under the directory 'webhelp' ChristianK created a directory called 'OpenPetra' in which the custom batch scripts are found, as well as a custom build.xml file. ChristianK also created the directory 'docsrc' under the 'OpenPetra' directory. It contains the input DocBook files that are processed by our installation of WebHelp ('userguides.xml' and 'tutorial.xml').

Custom Batch Scripts

configure.bat

Sets CLASSPATH and ANT_HOME and appends the Apache bin directory to the PATH.

One needs to run this script once from a command shell window to configure the WebHelp toolchain on jonah.

create-webhelp-OpenPetra.bat / create-webhelp-Tutorial-OpenPetra.bat

Invoke the creation of WebHelp, specifying the input and output directories.

• create-webhelp-OpenPetra.bat creates the application help.
  • It works with the input file 'userguides.xml' and stores the generated HTML files in the 'output-userguides' subdirectory.
• create-webhelp-Tutorial-OpenPetra.bat creates the tutorial.
  • It works with the input file 'tutorial.xml' and stores the generated HTML files in the 'output-tutorial' subdirectory.

One can run those batch scripts as often as one wants to create WebHelp output from the input files. One has to do this in the same command shell in which configure.bat was run so WebHelp is configured properly!

Custom build.xml Files

In webhelp Folder

The line in the build.xml file where it says

style="../profiling/profile.xsl">

needs to be changed to

style="../../profiling/profile.xsl">

to allow the running of WebHelp from the 'OpenPetra' subfolder.

In 'OpenPetra' Subfolder

Content of the custom build.xml file, which resides in C:\OpenPetra_SingleSourcePublishing\WebHelp processing stack (separate of Calenco!)\CURRENT\webhelp\OpenPetra\:

<project>
  <import file="../build.xml"/>
</project>

This file doesn't add any customisation, but it must be in place for Ant to work.

build.properties Customisations

The lines in the build.properties file where it says

branding=docbook
brandname=DocBook

need to be changed to

branding=openpetra
brandname=OpenPetra

The line in the build.properties file where it says

admon.graphics=0

needs to be changed to

admon.graphics=1

to turn on the showing of icons in the 'Warning', 'Info', etc. sections of the application help (Example where they are shown: 'To Add, Edit or Delete a Currency' topic in 'Finance Module Set-up').

XSL File Customisations

In the subfolder 'webhelp\xsl\' there is a file called 'webhelp.xsl'. This file needs to be customised as follows:

The line in the webhelp.xsl file where it says

<xsl:param name="chunk.section.depth" select="1"/>

needs to be changed to

<xsl:param name="chunk.section.depth" select="2"/>

to break up the DocBook input document into more HTML pages than it would be done by default. This means that the HTML pages don't get as long, which is desirable.

Immediately after the line in the webhelp.xsl file where it says

<link rel="stylesheet" type="text/css" href="{$webhelp.common.dir}css/positioning.css"/>

a new line with the following content needs to be inserted:

<link rel="stylesheet" type="text/css" href="../common/css/custom_openpetra.css"/>

This adds a custom CSS stylesheet that we want to use for the upcoming OpenPetra Application Help (see here).

At the very end of the file, before the closing </xsl:stylesheet> Element, insert the following text:

<xsl:template match="processing-instruction('linebreak')">
  <br/>
</xsl:template>

This makes sure that manual linebreaks that are specified in the input DocBook file are actually rendered as linebreaks in the HTML document.

The better way of doing it: utilising a 'Customisation Layer'

The approach described above is directly changing a file that is shipped with DocBook XML-NS, 'webhelp.xsl'. The better way of customising the XSL transformation settings is to employ a 'Customisation Layer'. Details about that approach can be found here. One of the advantages is that the custom content of the 'webhelp.xsl' file doesn't need to be merged again and again when newer versions of DocBook XML-NS are installed.

There was too little time in the scope of the student project to look into creating a 'Customisation Layer', but this should definitely be looked at when we set up the DocBook WebHelp toolchain properly for the regular creation of WebHelp from Confluence.

CSS Customisations

In the subfolder 'webhelp\template\common\css\' a file called 'custom_openpetra.css' needs to be created. The file content needs to be as follows:

/* Ensure italic text is appearing in italic */
.italics {font-style: italic;}
/* Ensure underlined text is appearing as underlined */
.underline{
    text-decoration: underline;
}

/* Custom styling of Note, Warning, Caution, Tip and Important document sections */
.note, .warning, .caution, .tip, .important {
    margin-bottom: 2px;
    padding: 2px 10px 2px 10px;
}
.note{
    background-color:#e9e9e9;
}
.warning{
    background-color:#ecd7e1;
}
.caution{
    background-color:#f1a8b3;
}
.tip{
    background-color:#f3ffc0;
}
.important{
    background-color:#f3dc77;
}

/* Create a 'button-like' appearance of text that is marked up using the 'Status' macro in Confluence! */
/* Note: \3A is the escape character for a colon (' : ') - that is needed to be able to use 'color:black' as a class name! */
.color\3A black{
    font-style: normal;
    background-color:#dde0c4;
    color: black;
    border: 1px solid gray;
    padding: 1px 6px 1px 6px;  
   
     -moz-border-radius: 7px;
    -webkit-border-radius: 7px;
    -khtml-border-radius: 7px;
    behavior: url(../common/css/ie-css3.htc);
    border-radius: 7px;    
}
 
/* Don't show any border on tables */
#content table td, #content table {border: 0px;}

Trick for Internet Explorer 6,7,8

IE 6,7,8 can't render rounded corners by default. There is a trick that enables them to do this: using the file ie-css3.htc. This file is referenced in the CSS file above and needs to be placed in the same directory as the CSS: subfolder 'webhelp\template\common\css\'. The file can be downloaded here.

Image Customisations

In order to use OpenPetra logos instead of the standard DocBook logos two image files need to be replaced:

• In folder \webhelp\template\common\images: replace 'logo.png' with a file of the same name that shows an OpenPetra logo (use an OpenPetra logo where the text 'open' is in black rather than in white/transparent!). This is the logo that gets displayed in the header all of the WebHelp HTML pages.
• In folder \webhelp\template: replace 'favicon.ico' with a file of the same name that is the FavIcon of the OpenPetra website (i.e. [1]). This is the icon that browsers display on a tab that contains OpenPetra WebHelp HTML pages.