View source for 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 [[Documentation of the customisation of the WebHelp processing stack#Custom_Batch_Scripts | custom batch scripts are found]], as well as a [[Documentation of the customisation of the WebHelp processing stack#In_'OpenPetra'_Subfolder | 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 <code>C:\OpenPetra_SingleSourcePublishing\WebHelp processing stack (separate of Calenco!)\CURRENT\webhelp\OpenPetra\</code>:

 <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 [[Documentation of the customisation of the WebHelp processing stack#CSS_Customisations | here]]).


At the very end of the file, before the closing <code>&lt;/xsl:stylesheet&gt;</code> Element, insert the following text:
 <xsl:template match="processing-instruction('linebreak')">
   &lt;br/&gt;
 </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 [http://www.sagehill.net/docbookxsl/CustomMethods.html 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 [http://code.google.com/p/box-shadow/downloads/detail?name=ie-css3.htc 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. [http://www.openpetra.org/wp-content/uploads/2011/05/favicon.ico]). ''This is the icon that browsers display on a tab that contains OpenPetra WebHelp HTML pages.''