Embedding XMLmind Web Help Compiler in a Java™ application

  1. Add whc_install_dir/lib/whc.jar and whc_install_dir/lib/snowball.jar to your CLASSPATH.

    JAR file snowball.jar is used to implement stemming. You may omit this file if you don't need stemming.

  2. The compiler expects its whc_template/ template directory to be found at any of the following locations:
    1. resource /whc_template/manifest.txt if found in whc.jar;
    2. directory_containing_whc.jar/whc_template/manifest.txt;
    3. directory_containing_whc.jar/../whc_template/manifest.txt.

    If this is not the case, you need to explicitly specify where is found file whc_template/manifest.txt (the manifest file of the template directory) by invoking static method setTemplateManifestURL. Example:

    Compiler.setTemplateManifestURL(manifestURL);

    Tip

    Running ant scjar in whc_install_dir/src/ allows to build whc_install_dir/lib/whc_sc.jar (SC for Self-Contained) which unlike whc.jar, embeds whc_template/.

  3. Create an instance of Compiler:
    Compiler compiler = new Compiler(null);

    Important: Do not share this instance between different threads, as this class is not thread-safe.

    If you don't want the error, warning and progress messages to be displayed on java.lang.System.err and to java.lang.System.out, implement interface Console and pass an instance of your implementation to the constructor.

  4. If you want the compiler to display progress messages, invoke Compiler.setVerbose(true). Example:
    compiler.setVerbose(verbose);
  5. Parameterize the output of the compiler by invoking either Compiler.parseParameters or individual configuration methods such as Compiler.setLayout, Compiler.setLocalJQuery, Compiler.setUILanguage, etc. Example:
    if (!compiler.parseParameters(params)) {
        /* Errors already printed on the Console.
           Nevertheless do something here. */
    }
  6. Finally invoke method Compiler.compile(URL[], URL, URL, File). Pass it an number of XHTML input files, generally also a TOC (Table Of Contents) specified in an XML input file and, optionally, some index entries also specified in another XML input file.

    The Web Help files are created in the directory specified by the last parameter of Compiler.compile(URL[], URL, URL, File).

    Example:

    if (!compiler.compile(xhtmlURLs, tocURL, indexURL, outDir)) {
        /* Errors other than java.io.IOExceptions 
           already printed on the Console.
           Nevertheless do something here. */
    }

    Notes

    The RELAX NG schema specifying the format of the TOC XML input file is found in whc_install_dir/doc/manual/schema/toc.rnc.

    The RELAX NG schema specifying the format of the Index XML input file is found in whc_install_dir/doc/manual/schema/index.rnc.

The overall code snippet (more or less copied from the main() method of whc_install_dir/src/com/xmlmind/whc/Compiler.java) is:

Compiler compiler = new Compiler(null);
compiler.setVerbose(verbose);
if (!compiler.parseParameters(params)) {
    /* Errors already printed on the Console.
       Nevertheless do something here. */
}
try {
    if (!compiler.compile(xhtmlURLs, tocURL, indexURL, 
                          outDir)) {
        /* Errors other than java.io.IOExceptions 
           already printed on the Console.
           Nevertheless do something here. */
    }
} catch (IOException e) {
    /* Do something with e. */
}