Creating WebHelp output

Overview

This page describes how to generate DocBook WebHelp output from a DocBook input file, using our customisation of the WebHelp toolchain.

Prerequisites

• Have a working set-up of the customisation of the WebHelp toolchain in place as described here.
• Have a DocBook input file (see next section).

Creation of the DocBook input file

We are editing the documents that form the basis for the DocBook WebHelp output (and the PDF output) in our Confluence Wiki installation.

To create a DocBook file for the OpenPetra application help do the following:

• Navigate to the 'Help Docs' Space, then to the 'OpenPetra Documentation' node, then to the 'OpenPetra User Guides and Help' child page.
• Open the 'Tools' menu and select 'Export to Docbook'. This invokes the 'Scroll Wiki DocBook Exporter' plug-in that is installed in our Confluence installation.
• On the 'General' tab, ensure the following options are set:
  • 'Choose a template': 'Article Style - Default Docbook Template'.
  • 'Export': 'This page and all children with label...'. Enter '^todo' in the TextBox below.
  • 'Ad hoc Workflows': 'Only published versions' CheckBox should normally not be checked.
  • Advanced:
    • 'Process toc macros' CheckBox should be checked;
    • 'Process children macros' CheckBox should be checked;
    • 'Replace thumbnails with corresponding high resolution images' CheckBox should not be checked;
    • 'Merge single, first heading and page title' CheckBox should be checked.
• On the 'Docbook Settings' tab, ensure that none of the options are set.
• Click 'Start Export'.
• After a few seconds (during which you will see a progress bar) a Download dialog will be displayed by your web browser, offering to download a ZIP file. Download this file to a location of your choice.
  • The ZIP file contains the actual docbook.xml file in the '\content\' subfolder and the images that are referenced by the docbook.xml file in the '\content\images\download\attachments\' subfolder.

Creation of the WebHelp output files

Putting the document source in place

• Extract the contents of the ZIP file that you have created in the previous step to a location of your choice.
• Copy the docbook.xml file from the extracted '\content\' subfolder to the '\webhelp\OpenPetra\docsrc' directory of our WebHelp Toolchain and rename the file to 'userguides.xml'.
• Copy the 'download' folder, which is contained in the extracted '\content\images\' folder, to the '\webhelp\template\content\images\' folder.

Invoking the WebHelp toolchain to generate WebHelp output

• Open a command shell window.
• Issue a 'cd' command, changing the current directory to the '\webhelp\OpenPetra\' directory of our WebHelp Toolchain.
• Execute configure.bat
• Execute create-webhelp-OpenPetra.bat.

The WebHelp toolchain starts processing the DocBook file and images and creates an output folder called 'output-userguides' under the '\webhelp\OpenPetra\' directory. This takes only a few seconds on a fast PC.

Once the processing is finished one can go to the '\webhelp\OpenPetra\output-userguides\' directory in Windows Explorer and open the generated 'index.html' file in a web browser of one's choice.

Result: OpenPetra Application Help in WebHelp Format

The result is the WebHelp output of the 'OpenPetra User Guides and Help' page in our Confluence installation.

The content of the folder '\webhelp\OpenPetra\output-userguides\' is completely self-contained, i.e. it does not reference anything outside of this folder and its subfolders.

This means...

• The contents of that folder can be shipped with an OpenPetra installation for offline access to the OpenPetra application help.
  • In this scenario the user can be totally disconnected from the Internet and the OpenPetra application help will display and work correctly [incl. search facility!]) in an Internet Browser;
• The contents of that folder can also be put on a server that is accessible on the Internet for on-line access to the OpenPetra application help.
  • In this scenario the user must be connected to the Internet. The OpenPetra application help will display and work correctly [incl. search facility!]) in an Internet Browser, displaying the content that is published on the server.
  • This scenario allows for central and more frequent updates to the OpenPetra application help than the offline scenario.