XMLmind Web Help Compiler

item What is XMLmind Web Help Compiler? 
item Installing XMLmind Web Help Compiler
item Using XMLmind Web Help Compiler as a command-line tool
item Embedding XMLmind Web Help Compiler in a Java™ application
item Modifying XMLmind Web Help Compiler
item History of changes

What is XMLmind Web Help Compiler?  Back to TOC

XMLmind Web Help Compiler (whc for short) allows to convert a set of static XHTML pages to a standalone, interactive, Web Help External link application running in a Web browser. The Web Help application generated by whc has the same features as the Microsoft® HTML Help External link Executable (hh.exe, Microsoft® .chm standard reader).

Example of Web Help application generated by XMLmind Web Help Compiler: XMLmind DITA Converter Manual Open in a new window.

XMLmind Web Help Compiler is free, open source, software, which like jQuery Open in a new window, is licensed under the terms of either the MIT License or the GNU General Public License (GPL) Version 2.

Features

How does it work?

XMLmind Web Help Compiler works a little like hhc.exe, Microsoft® HTML Help compiler. It takes as its input:

Unlike hhc.exe which generates a single .chm file, whc:

Installing XMLmind Web Help Compiler  Back to TOC

Requirements

In order to run (or recompile) XMLmind Web Help Compiler: Java™ 1.6+.

In order to run a Web Help application generated by whc: a recent, preferably fast, Web browser. The Web Help applications generated by whc have been tested against Firefox, Google Chrome, Safari, Opera, Internet Explorer 11, Edge.

Installation

Simply unzip whc-X_Y_Z.zip in any directory.

Make sure that you have a Java™ 1.6+ runtime installed on your machine. To check this, please open a command window and type "java -version" followed by Enter. You should get something looking like this:

C:\> java -version
java version "1.8.0_144"
Java(TM) SE Runtime Environment (build 1.8.0_144-b01)
Java HotSpot(TM) 64-Bit Server VM (build 25.144-b01, mixed mode)

After that, you can run whc by simply executing java -jar whc_install_dir/lib/whc.jar.

C:\> mkdir XMLmind
C:\> cd XMLmind
C:\XMLmind> unzip whc-2_0_0.zip
C:\XMLmind> dir whc-2_0_0
... <DIR> doc
... <DIR> LEGAL
... <DIR> lib
...
C:\XMLmind> java -jar whc-2_0_0\lib\whc.jar
usage: java -jar whc.jar [-v]
    [-p param_name param_value]*
    ...

Contents of the installation directory

doc/
doc/index.html
doc/api/
Contains the documentation of whc. You'll find in doc/api/ the reference manual of the Java API of whc (as generated by javadoc).
LEGAL.txt
LEGAL/
Contains legal information about whc and about third-party components used in whc.
lib/
lib/whc.jar
lib/snowball.jar
Contains the compiled code of whc. File snowball.jar is used to implement stemming.
sample/
sample/schema/toc.rnc
sample/schema/index.rnc
Contains sample XHTML input files as well as a sample toc.xml and a sample index.xml. The sample/schema/ subdirectory contains the RELAX NG schemas to which the TOC XML file (e.g. toc.xml) and the Index XML file (e.g. index.xml) must conform.
scripts/
Contains script files allowing to update whc_template/ after modifying templatesrc/.
src/
src/build.xml
Contains the Java source code of whc. src/build.xml is an ant Open in a new window build file which allows to rebuild lib/whc.jar.
templatesrc/
templatesrc/common/_wh/
templatesrc/layout_name/_wh/
Contains the XHTML, CSS and JavaScript source files needed to rebuild whc_template/layout_name/.

Each templatesrc/layout_name/ folder also contains a number of XHTML pages, page_XXX.html. These pages may be used to quickly test the CSS and JavaScript source files found in templatesrc/layout_name/_wh/. More information in Modifying XMLmind Web Help Compiler.

whc_template/
whc_template/layout_name/file.list
whc_template/layout_name/page.html
whc_template/layout_name/_wh/
The template directory of whc. whc copies a number of resource files found in whc_template/layout_name/_wh/ and also a number of XHTML elements extracted from whc_template/layout_name/page.html in order to generate a Web Help application.

Using XMLmind Web Help Compiler as a command-line tool  Back to TOC

Usage:

java -jar whc_install_dir/lib/whc.jar [-v]
    [-p param_name param_value]*
    [-toc toc_xml_URL_or_file]
    [-index index_xml_URL_or_file]
    output_directory [xhtml_URL_or_file]+

Converts a number of XHTML input files xhtml_URL_or_file to a Web Help application created in output directory output_directory.

It's possible to specify "-" for output_directory. In this case, all the XHTML input files are “decorated” in place and hence, must be found in the same directory.

Options

-v
Display progress messages on the console.
-p param_name param_value
Parameterize the output of whc.

The reference of parameters supported by whc is found below.

-toc toc_xml_URL_or_file
Generate a Table of Contents.

This XML input file must conform to the following RELAX NG schema: whc_install_dir/sample/schema/toc.rnc. A sample TOC XML file is found in whc_install_dir/sample/toc.xml.

Note a Table of Contents is systematically generated, even when the -toc option has not been specified. By default, whc generates a simple, flat, TOC comprising the titles of the XHTML input pages.

-index index_xml_URL_or_file
Generate an Index.

This XML input file must conform to the following RELAX NG schema: whc_install_dir/sample/schema/index.rnc. A sample Index XML file is found in whc_install_dir/sample/index.xml.

Parameters

About prefix "wh-"

Whc also accepts the parameters below prefixed with "wh-". For example, it accepts jquery-theme as well as wh-jquery-theme. This prefix is required when whc is embedded in XMLmind DITA Converter, XMLmind XSL Utility and XMLmind XML Editor.

Parameter Value Description

add-index

yes or no.

Default value: no.

Specifies whether an "index.html" file should be automatically created if this output file does not already exist.

This automatic "index.html" file is created simply by copying the first page generated out of the first file passed to the compiler.

Note that the actual file suffix used for this file is not always ".html". It's the same file suffix as the copied page (if no suffix, ".html").

collapse-toc

yes or no.

Default value: no.

Specifies whether the TOC should be initially collapsed.

default-language

A language code conforming RFC 3066. Examples: de, fr-CA.

Default value: en.

Specifies the language used when an XHTML input page does not specify a xml:lang or lang attribute on its html root element.

index-numbers

yes or no.

Default value: no.

Specifies whether words looking like numbers are to be indexed.

Examples of such number-like words: 3.14, 3,14, 3times4equals12, +1, -1.0, 3px, 1,2cm, 100%, 1.0E+6, 1,000.00$.

jquery

Relative or absolute URI. A relative URI is relative to the URI of a page of the Web Help.

Default value: absolute URI of the corresponding file found on the Google CDN.

Specifies the location of the JavaScript file containing jQuery Open in a new window.

Example: http://ajax.aspnetcdn.com/ajax/ jQuery/jquery-3.2.1.min.js.

Specifying an "https:" URL is recommended when the generated Web Help is stored on an HTTPS server.

jquery-css

Relative or absolute URI. A relative URI is relative to the URI of a page of the Web Help.

Default value: absolute URI of the corresponding file found on the Google CDN.

Specifies the location of the CSS stylesheet of jQuery UI Open in a new window.

Example: http://ajax.aspnetcdn.com/ajax/ jquery.ui/1.12.1/themes/redmond/jquery-ui.css.

Specifying an "https:" URL is recommended when the generated Web Help is stored on an HTTPS server.

jquery-custom-theme

Filename or absolute URI of a .zip file created using JQueryUI ThemeRoller Open in a new window.

No default.

Specifies a .zip file created using JQueryUI ThemeRoller Open in a new window containing a custom JQueryUI theme. Example: jquery-ui-1.12.1.custom.zip.

The files comprising the custom theme are copied to _wh/jquery/, where _wh/ is the directory containing the other Web Help files.

Ignored if parameter jquery-css has been used to specify the CSS stylesheet of jQuery UI.

jquery-theme

The name of a theme. Examples: redmond, cupertino.

Default value: smoothness.

Specifies the name of the jQuery UI Open in a new window theme used by the compiler.

Ignored if parameter jquery-css or jquery-custom-theme have been used to specify the CSS stylesheet of jQuery UI.

jquery-ui

Relative or absolute URI. A relative URI is relative to the URI of a page of the Web Help.

Default value: absolute URI of the corresponding file found on the Google CDN.

Specifies the location of the JavaScript file containing jQuery UI Open in a new window.

Example: http://ajax.aspnetcdn.com/ajax/ jquery.ui/1.12.1/jquery-ui.min.js.

Specifying an "https:" URL is recommended when the generated Web Help is stored on an HTTPS server.

layout

The name of a layout.

Default value: classic.

Selects a layout for the generated Web Help.

For now, only 2 layouts are supported: classic and simple.

local-jquery

yes or no.

Default value: no.

Specifies whether all jQuery files should be copied to _wh/jquery/, where _wh/ is the directory containing the other Web Help files.

By default, the jQuery files are accessed from the Web (typically from a CDN).

Note that this parameter is applied after JQuery and JQueryUI have been possibly customized using parameters jquery, jquery-ui, jquery-css, jquery-theme and jquery-custom-theme. For example, "-p jquery-theme cupertino -p local-jquery yes" copies the Cupertino CSS files to _wh/jquery/.

use-stemming

yes or no.

Default value: yes.

Specifies whether stemming should be used to implement the search facility.

By default, stemming is used whenever possible, that is,

  1. when the main language of the XHTML pages to be compiled can be determined;
  2. when this main language is one of: Danish, Dutch, English, Finnish, French, German, Hungarian, Italian, Norwegian, Portuguese, Russian, Spanish, Swedish, Romanian, Turkish.

The main language of the XHTML pages to be compiled is specified by the lang or xml:lang attribute found on the root element of the first XHTML page; otherwise the main language is specified using parameter default-language; otherwise, it is assumed to be "en".

user-css

Filename or absolute URI of a CSS file. A relative filename is relative to the current working directory.

Specifies the user's CSS stylesheet which is to be added to an XHTML page decorated by the compiler.

This file is copied to output_directory/_wh/user/.

Sample user's CSS wh_resources/header_footer.css Open in a new window as used in the following example:

-p wh-user-header wh_resources/header.html \
-p wh-user-footer wh_resources/footer.html \
-p wh-user-css wh_resources/header_footer.css \
-p wh-user-resources wh_resources/header_footer_files

Filename or absolute URI of an XHTML file. A relative filename is relative to the current working directory.

Specifies the user's footer which is to be added to each XHTML page decorated by the compiler.

The content of the body element of user-footer is inserted as is in the <div id="wh-footer"> found in each XHTML page decorated by the compiler.

Same remark as for parameter user-header about the resources referenced by a user's footer.

Sample user's footer wh_resources/footer.html Open in a new window as used in the following example:

-p wh-user-header wh_resources/header.html \
-p wh-user-footer wh_resources/footer.html \
-p wh-user-css wh_resources/header_footer.css \
-p wh-user-resources wh_resources/header_footer_files

user-header

Filename or absolute URI of an XHTML file. A relative filename is relative to the current working directory.

Specifies the user's header which is to be added to each XHTML page decorated by the compiler.

The content of the body element of user-header is inserted as is in the <div id="wh-header"> found in each XHTML page decorated by the compiler.

If a user's header references resources (e.g. image files), then these resources must either be referenced using absolute URLs or these resources must be found in a user's resource directory and parameter user-resources must be specified.

Example:

  • The user's resource directory is called header_footer_files/ and contains header_footer_files/logo100x50.png.
  • whc is passed parameters -p user-resources PATH_TO/header_footer_files and -p user-header PATH_TO/header.html.
  • header.html looks like this:
    <html>
    ...
    <body>
    ...
    <img src="_wh/user/header_footer_files/¬
    logo100x50.png" />
    ...
    </body>
    </html>

    Notice the path used to reference logo100x50.png.

Sample user's header wh_resources/header.html Open in a new window as used in the following example:

-p wh-user-header wh_resources/header.html \
-p wh-user-footer wh_resources/footer.html \
-p wh-user-css wh_resources/header_footer.css \
-p wh-user-resources wh_resources/header_footer_files

user-resources

Filename or absolute "file:" URI of a directory. URI schemes other than "file" (e.g. "http") are not supported for this parameter. A relative filename is relative to the current working directory.

Specifies a user's resource directory which is to be recursively copied to output_directory/_wh/user/.

This directory typically contains image files referenced by the user's header, footer or CSS stylesheet.

Sample user's resource directory wh_resources/header_footer_files/ Open in a new window as used in the following example:

-p wh-user-header wh_resources/header.html \
-p wh-user-footer wh_resources/footer.html \
-p wh-user-css wh_resources/header_footer.css \
-p wh-user-resources wh_resources/header_footer_files

Embedding XMLmind Web Help Compiler in a Java™ application  Back to TOC

Please refer to the documentation of the API of XMLmind Web Help Compiler and more precisely to "How to embed XMLmind Web Help Compiler in a Java™ application".

Modifying XMLmind Web Help Compiler  Back to TOC

History of changes  Back to TOC

v2.0.0 (September 18, 2017)

Added parameter layout which may be used to select a layout for the generated Web Help. Default layout is called classic. New layout is called simple.

v1.4.5 (August 21, 2017)

Added workaround for an Internet Explorer 11/Edge bug: expanding a collapsed TOC entry displayed subentries having two bullets instead of just one.

v1.4.4 (June 10, 2017)

v1.4.3 (April 27, 2017)

v1.4.2_03 (April 14, 2017)

v1.4.2_02 (March 30, 2017)

Bug fixes:

v1.4.2_01 (March 13, 2017)

Minor internal tweaks.

v1.4.2 (November 7, 2016)

Upgraded jQuery to v3.1.1, jQuery UI to v1.12.1. This major upgrade required making a number of changes in the JavaScript™ code of XMLmind Web Help Compiler, so this may have added minor bugs. If, in the generated Web Help, you find anything which does not work as expected, please be kind enough to file a bug report (mailto:ditac-support@xmlmind.com).

v1.4.1_01 (August 18, 2016)

Upgraded jQuery to v2.2.4, which implies that the Web Help generated by whc no longer supports Internet Explorer 8 and older versions.

v1.4.1 (April 8, 2016)

v1.4.0_05 (February 22, 2016)

v1.4.0_04 (October 26, 2015)

Minor internal tweaks.

v1.4.0_03 (July 30, 2015)

XMLmind Web Help Compiler now copies the background styles possibly found in the body element of an input XHTML page. This is needed to support the watermark feature implemented by ditac v2.5.6+.

v1.4.0_02 (June 18, 2015)

Upgraded jQuery to v1.11.3, jQuery UI to v1.11.4.

v1.4.0_01 (January 22, 2015)

Upgraded jQuery to v1.11.2, jQuery UI to v1.11.2.

v1.4 (September 17, 2014)

Enhancements:

Bug fixes:

v1.3.0_03 (April 04, 2014)

Now requires Java™ 1.6+ in order to compile and run.

v1.3.0_02 (February 12, 2014)

Upgraded jQuery to v1.11.0, jQuery UI to v1.10.4.

v1.3 (October 29, 2013)

v1.2.1 (July 8, 2013)

v1.2.0_01 (May 20, 2013)

Minor internal tweaks.

v1.2.0 (February 18, 2013)

v1.1.4 (September 11, 2012)

Added message translations to de, es, it, ja, pl, ru, zh-CN, zh-TW, thanks to a contribution made by Jirka Kosek (http://xmlguru.cz/).

v1.1.3 (June 15, 2012)

Add a Print button to the toolbar found in the TOC pane.

v1.1.2 (April 30, 2012)

Minor internal tweaks.

v1.1.1 (March 13, 2012)

New collapse-toc parameter specifies whether the TOC should be initially collapsed.

v1.1 (January 10, 2012)

Whc now accepts raw index files. A raw index is an index were entries have not been merged and sorted. A example of such file is found in whc_install_dir/sample/raw_index.xml. (Compare this file with whc_install_dir/sample/index.xml.)

This enhancement was motivated by the fact that we have found that generating an index were entries are merged and sorted is almost impossible using XSLT 1. This task seems to require XSLT 2 features (e.g. grouping).

v1.0 (December 6, 2011)

First release.