com.xmlmind.whc
Class Compiler

java.lang.Object
  extended by com.xmlmind.whc.Compiler

public final class Compiler
extends Object

The Web Help Compiler.

This class is not thread-safe. That is, create and use one instance per thread. However an instance may be reused by invoking compile(URL[], URL, URL, File) several times.


Field Summary
static String VERSION
          The version number of this Compiler.
 
Constructor Summary
Compiler(Console console)
          Constructs a compiler.
 
Method Summary
 boolean compile(File[] xhtmlFiles, File tocFile, File indexFile, File outDir)
          Convenience method equivalent to compile(URL[], URL, URL, File), except that the arguments are Files and not URLs.
 boolean compile(URL[] xhtmlURLs, URL tocURL, URL indexURL, File outDir)
          Compiles a Web Help application by ``decorating'' specified XHTML pages.
 boolean getCollapseTOC()
          Returns true if the TOC is to be initially collapsed; otherwise returns false.
 Console getConsole()
          Returns the console used to display error, warning and progress messages.
 String getDefaultLanguage()
          Returns the language used when the XHTML page being parsed does not specify a xml:lang or lang attribute on its html root element.
 boolean getIndexNumbers()
          Returns true if words looking like numbers are to be indexed; otherwise returns false.
 String getJQuery()
          Returns the location of the JavaScript file containing jQuery.
 String getJQueryCSS()
          Returns the location of the CSS stylesheet of jQuery UI.
 URL getJQueryCustomTheme()
          Returns the URL of a .zip file containing a custom theme created using jQuery UI ThemeRoller.
 String getJQueryTheme()
          Returns the name of the jQuery UI theme used by the compiler.
 String getJQueryUI()
          Returns the location of the JavaScript file containing jQuery UI.
 String getLayout()
          Returns the selected selected for the generated Web Help.
static URL getTemplateManifestURL()
          Returns the location of whc_template/classic/file.list, May return null.
 URL getUserCSS()
          Returns the user's CSS stylesheet to be added to an XHTML page decorated by the compiler.
 URL getUserFooter()
          Returns the user's footer to be added to an XHTML page decorated by the compiler.
 URL getUserHeader()
          Returns the user's header to be added to an XHTML page decorated by the compiler.
 File getUserResources()
          Returns the user's resource directory which is recursively copied to output_directiry/_wh/user/.
 boolean getUseStemming()
          Returns true if stemming is to be used to implement the search by contents facility; otherwise returns false.
 boolean isLocalJQuery()
          Returns true if the jQuery files must be copied to the local resource directory created by this compiler; false otherwise.
 boolean isVerbose()
          Returns the verbosity of this compiler.
static void main(String[] args)
           
 boolean parseParameters(String[] parameters)
          Parses specified parameters invoking setJQueryTheme(java.lang.String), setJQuery(java.lang.String), ..., setDefaultLanguage(java.lang.String), as needed to.
 boolean parseParameters(String[] parameters, URL baseURL)
          For internal use only.
 void setCollapseTOC(boolean collapse)
          Specifies whether the TOC should be initially collapsed.
 void setDefaultLanguage(String lang)
          Specifies the language used when the XHTML page being parsed does not specify a xml:lang or lang attribute on its html root element.
 void setIndexNumbers(boolean index)
          Specifies whether words looking like numbers are to be indexed.
 void setJQuery(String location)
          Specifies the location of the JavaScript file containing jQuery.
 void setJQueryCSS(String location)
          Specifies the location of the CSS stylesheet of jQuery UI.
 void setJQueryCustomTheme(URL customThemeURL)
          Specifies the URL of a .zip file containing a custom theme created using jQuery UI ThemeRoller.
 void setJQueryTheme(String name)
          Specifies the name of the jQuery UI theme used by the compiler.
 void setJQueryUI(String location)
          Specifies the location of the JavaScript file containing jQuery UI.
 void setLayout(String layout)
          Selects a layout for the generated Web Help.
 void setLocalJQuery(boolean local)
          Specifies whether the jQuery files must be copied to the local resource directory created by this compiler.
static void setTemplateManifestURL(URL url)
          Specifies the location of whc_template/classic/file.list, the manifest file listing all the files used by the compiler to ``decorate'' an XHTML page.
 void setUserCSS(URL url)
          Specifies the user's CSS stylesheet which is to be added to an XHTML page decorated by the compiler.
 void setUserFooter(URL url)
          Specifies the user's footer which is to be added to an XHTML page decorated by the compiler.
 void setUserHeader(URL url)
          Specifies the user's header which is to be added to an XHTML page decorated by the compiler.
 void setUserResources(File dir)
          Specifies a user's resource directory which is to be recursively copied to output_directory/_wh/user/.
 void setUseStemming(boolean stemming)
          Specifies whether stemming should be used to implement the search by contents facility.
 void setVerbose(boolean verbose)
          Specifies the verbosity of this compiler.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

VERSION

public static final String VERSION
The version number of this Compiler.

See Also:
Constant Field Values
Constructor Detail

Compiler

public Compiler(Console console)
Constructs a compiler.

Parameters:
console - the console used to display error, warning and progress (setVerbose(boolean)) messages. May be null in which case these messages are printed System.err and System.out.
Method Detail

setTemplateManifestURL

public static void setTemplateManifestURL(URL url)
Specifies the location of whc_template/classic/file.list, the manifest file listing all the files used by the compiler to ``decorate'' an XHTML page.

When this location has not been explicitly specified, it is searched in the following location:

  1. resource /whc_template/classic/file.list if found in whc.jar,
  2. whc_jar_dir/whc_template/classic/file.list,
  3. whc_jar_dir/../whc_template/classic/file.list.

Parameters:
url - location of whc_template/classic/file.list. May be null in which case whc_template/classic/file.list will be searched in the above locations.
See Also:
getTemplateManifestURL()

getTemplateManifestURL

public static URL getTemplateManifestURL()
Returns the location of whc_template/classic/file.list, May return null.

See Also:
setTemplateManifestURL(java.net.URL)

getConsole

public Console getConsole()
Returns the console used to display error, warning and progress messages. May return null.


setVerbose

public void setVerbose(boolean verbose)
Specifies the verbosity of this compiler.

By default the compiler is not verbose.

Parameters:
verbose - if true, display progress messages on the console.
See Also:
isVerbose()

isVerbose

public boolean isVerbose()
Returns the verbosity of this compiler.

See Also:
setVerbose(boolean)

setLayout

public void setLayout(String layout)
Selects a layout for the generated Web Help.

Parameters:
layout - layout name. For now, only "classic" and "simple" layouts are supported. May be null in which case "classic" is used.
See Also:
getLayout()

getLayout

public String getLayout()
Returns the selected selected for the generated Web Help.

See Also:
setLayout(java.lang.String)

setLocalJQuery

public void setLocalJQuery(boolean local)
Specifies whether the jQuery files must be copied to the local resource directory created by this compiler.

Default: Not local. jQuery files are downloaded from the Web by the Web Help.

Parameters:
local - true the jQuery files must be local to the Web Help; false if they are to be downloaded from the Web by the Web Help
See Also:
isLocalJQuery()

isLocalJQuery

public boolean isLocalJQuery()
Returns true if the jQuery files must be copied to the local resource directory created by this compiler; false otherwise.

See Also:
setLocalJQuery(boolean)

setJQueryTheme

public void setJQueryTheme(String name)
Specifies the name of the jQuery UI theme used by the compiler.

By default the compiler uses the smoothness theme.

This specification is ignored if setJQueryCSS(java.lang.String) has been used to specify the CSS stylesheet of jQuery UI or if setJQueryCustomTheme(java.net.URL) has been used to specify a custom theme.

Parameters:
name - name of a jQuery UI theme. Examples: redmond, cupertino.
See Also:
getJQueryTheme()

getJQueryTheme

public String getJQueryTheme()
Returns the name of the jQuery UI theme used by the compiler. May return null.

See Also:
setJQueryTheme(java.lang.String)

setJQueryCustomTheme

public void setJQueryCustomTheme(URL customThemeURL)
Specifies the URL of a .zip file containing a custom theme created using jQuery UI ThemeRoller.

By default the compiler uses the smoothness theme.

This specification is ignored if setJQueryCSS(java.lang.String) has been used to specify the CSS stylesheet of jQuery UI.

Parameters:
customThemeURL - the URL of a .zip file containing a custom theme created using jQuery UI ThemeRoller
See Also:
getJQueryCustomTheme()

getJQueryCustomTheme

public URL getJQueryCustomTheme()
Returns the URL of a .zip file containing a custom theme created using jQuery UI ThemeRoller. if this URL has been specified using setJQueryCustomTheme(java.net.URL). Returns null otherwise.


setJQuery

public void setJQuery(String location)
Specifies the location of the JavaScript file containing jQuery.

By default the compiler references a file found on the Google CDN.

Parameters:
location - relative or absolute URI of the JavaScript file containing jQuery.
See Also:
getJQuery()

getJQuery

public String getJQuery()
Returns the location of the JavaScript file containing jQuery. May return null.

See Also:
setJQuery(java.lang.String)

setJQueryUI

public void setJQueryUI(String location)
Specifies the location of the JavaScript file containing jQuery UI.

By default the compiler references a file found on the Google CDN.

Parameters:
location - relative or absolute URI of the JavaScript file containing jQuery UI.
See Also:
getJQueryUI()

getJQueryUI

public String getJQueryUI()
Returns the location of the JavaScript file containing jQuery UI. May return null.

See Also:
setJQueryUI(java.lang.String)

setJQueryCSS

public void setJQueryCSS(String location)
Specifies the location of the CSS stylesheet of jQuery UI.

By default the compiler references a CSS file found on the Google CDN.

Parameters:
location - relative or absolute URI of the CSS stylesheet of jQuery UI.
See Also:
getJQueryCSS()

getJQueryCSS

public String getJQueryCSS()
Returns the location of the CSS stylesheet of jQuery UI. May return null.

See Also:
setJQueryCSS(java.lang.String)

setUserHeader

public void setUserHeader(URL url)
Specifies the user's header which is to be added to an XHTML page decorated by the compiler.

Parameters:
url - location of an XHTML page. The content of its body element is inserted as is in the div id="wh-header" found in an XHTML page decorated by the compiler.
See Also:
getUserHeader()

getUserHeader

public URL getUserHeader()
Returns the user's header to be added to an XHTML page decorated by the compiler. May return null.

See Also:
setUserHeader(java.net.URL)

setUserFooter

public void setUserFooter(URL url)
Specifies the user's footer which is to be added to an XHTML page decorated by the compiler.

Parameters:
url - location of an XHTML page. The content of its body element is inserted as is in the div id="wh-footer" found in an XHTML page decorated by the compiler.
See Also:
getUserFooter()

getUserFooter

public URL getUserFooter()
Returns the user's footer to be added to an XHTML page decorated by the compiler. May return null.

See Also:
setUserFooter(java.net.URL)

setUserCSS

public void setUserCSS(URL url)
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/.

Parameters:
url - location of a CSS stylesheet
See Also:
getUserCSS(), setUserResources(java.io.File)

getUserCSS

public URL getUserCSS()
Returns the user's CSS stylesheet to be added to an XHTML page decorated by the compiler. May return null.

See Also:
setUserCSS(java.net.URL)

setUserResources

public void setUserResources(File dir)
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.

Parameters:
dir - a directory to be recursively copied to output_directory/_wh/user/.
See Also:
getUserResources(), getUserHeader(), setUserFooter(java.net.URL), setUserCSS(java.net.URL)

getUserResources

public File getUserResources()
Returns the user's resource directory which is recursively copied to output_directiry/_wh/user/. May return null.

See Also:
setUserResources(java.io.File)

setDefaultLanguage

public void setDefaultLanguage(String lang)
Specifies the language used when the XHTML page being parsed does not specify a xml:lang or lang attribute on its html root element.

This language is needed by the full-text indexer component of this compiler.

Parameters:
lang - the default language of an XHTML page. A language code conforming RFC 3066. Examples: "de", "fr-CA". May be null in which case "en" is used.
See Also:
getDefaultLanguage()

getDefaultLanguage

public String getDefaultLanguage()
Returns the language used when the XHTML page being parsed does not specify a xml:lang or lang attribute on its html root element.

See Also:
setDefaultLanguage(java.lang.String)

setCollapseTOC

public void setCollapseTOC(boolean collapse)
Specifies whether the TOC should be initially collapsed.

By default, the TOC is initially expanded.

Parameters:
collapse - if true, the TOC should be initially collapsed.
See Also:
getCollapseTOC()

getCollapseTOC

public boolean getCollapseTOC()
Returns true if the TOC is to be initially collapsed; otherwise returns false.

See Also:
setCollapseTOC(boolean)

setUseStemming

public void setUseStemming(boolean stemming)
Specifies whether stemming should be used to implement the search by contents facility.

By default, stemming must be used whenever possible, that is, when the main language of the document can be determined and when this main language is one of: danish, dutch, english, finnish, french, german, hungarian, italian, norwegian, portuguese, russian, spanish, swedish, romanian, turkish.

Parameters:
stemming - if true, stemming is to implement the search by contents facility
See Also:
getUseStemming(), setDefaultLanguage(java.lang.String)

getUseStemming

public boolean getUseStemming()
Returns true if stemming is to be used to implement the search by contents facility; otherwise returns false.

See Also:
setUseStemming(boolean)

setIndexNumbers

public void setIndexNumbers(boolean index)
Specifies whether words looking like numbers are to be indexed.

By default, words looking like numbers are not indexed.

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

See Also:
getIndexNumbers()

getIndexNumbers

public boolean getIndexNumbers()
Returns true if words looking like numbers are to be indexed; otherwise returns false.

See Also:
setIndexNumbers(boolean)

parseParameters

public boolean parseParameters(String[] parameters)
Parses specified parameters invoking setJQueryTheme(java.lang.String), setJQuery(java.lang.String), ..., setDefaultLanguage(java.lang.String), as needed to.

Parameters:
parameters - a list of parameter name/parameter value pairs. A parameter may be prefixed by "wh-", in which case this prefixed is stripped.
Returns:
true if the parameters have been successfully parsed; false otherwise (in which case error messages are displayed on the console).

parseParameters

public boolean parseParameters(String[] parameters,
                               URL baseURL)
For internal use only. Not part of the public, documented, API.


compile

public boolean compile(File[] xhtmlFiles,
                       File tocFile,
                       File indexFile,
                       File outDir)
                throws IOException
Convenience method equivalent to compile(URL[], URL, URL, File), except that the arguments are Files and not URLs.

Throws:
IOException

compile

public boolean compile(URL[] xhtmlURLs,
                       URL tocURL,
                       URL indexURL,
                       File outDir)
                throws IOException
Compiles a Web Help application by ``decorating'' specified XHTML pages.

Decorating means: adding a few extra XHTML elements to each page. These elements typically point to CSS, image and JavaScript resources found in the output_directory/_wh/ directory.

Parameters:
xhtmlURLs - the list of XHTML input files to be ``decorated'' by the compiler.
tocURL - the XML file specifying the entries of the Table Of Contents. May be null in which case a simple TOC comprising the list of the titles of the XHTML input files is automatically used to populate the Contents tab.

This XML file must conform to RELAX NG schema toc.rnc.

indexURL - the XML file specifying the entries of the Index. May be null in which case the Index tab is not created.

This XML file must conform to RELAX NG schema index.rnc.

outDir - the output directory. May be null in which case the XHTML input files are modified in place.

When the XHTML input files are decorated in place, they must all be found in the same directory.

Returns:
true if the Web Help application has been successfully generated; false otherwise (in which case error messages are displayed on the console).
Throws:
IOException - if an I/O error occurs while reading or writing files.

main

public static void main(String[] args)