GeWorkbench Online Help Development
From Informatics
Contents |
Introduction and resources
geWorkbench Online Help uses the Java help 2.0 system.
Out of the entire Java Help distribution, only a single file is apparently used: jhall.jar.
The home page for Java Help at Sun is:
http://java.sun.com/javase/technologies/desktop/javahelp/index.jsp
The download page where the software and user documentation can be obtained is:
http://java.sun.com/javase/technologies/desktop/javahelp/download_binary.html#userguide
Overview of file structure
The help system uses several files to define the help menu entries and associate them with actual HTML files. We will use first use the MINDy component as examples. The name of the main MINDy component is MindyAnalysis.java. At runtime, geWorkbench looks dynamically in each component for a file with the component main class base name plus the suffix ".cwb.xml". This file tells geWorkbench where to find the Java Help set for that component. There is no higher-level file listing help sets, they are all discovered dynamically as just described. In the present example, this file is named "MindyAnalysis.cwb.xml". That is, it is formed by adding ".cwb.xml" to the base name of the Java class.
Table of Contents (TOC) entries are defined by tags which are associated with display names and with specific HTML files, as shown in the following hierarchy of relationships:
org/geworkbench/components/mindy/
|-----MindyAnalysis.java # Main java class for this analysis component.
|-----MindyAnalysis.cwb.xml # Links the component help set mindyHelpSet.hs into the geWorkbench help menu.
|
|-----help/
|-----mindyHelpSet.hs # gives the names of the TOC and mapping files.
| |----->MINDYtoc.xml # associates TOC tags with display names e.g. "overview" -> "Overview"
| |----->mindy.jhm # maps TOC tags to specific HTML files, e.g. "overview" to the "mindy.HTML" file.
| |----->mindy.HTML
|
|
|-----ncicb.css
|
|-----mindy_files/ # contains any image files referenced in the mindy.HTML file.
Example 1: Mindy Help Set - single TOC entry
MindyAnalysis.cwb.xml
MindyAnalysis.cwb.xml defines its component class and the path to the help set file "mindHelpSet.hs":
<component-descriptor xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="Descriptor Schema.xsd"> <component class="org.geworkbench.components.mindy.MindyAnalysis"> <online-help helpSet="org/geworkbench/components/mindy/help/mindyHelpSet.hs"/> </component> </component-descriptor>
mindyHelpSet.hs
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE helpset PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 1.0//EN"
"http://java.sun.com/products/javahelp/helpset_1_0.dtd">
<?TestTarget The help set file for the MINDY component.?>
<helpset version="1.0">
<title>MINDY</title>
<maps>
<homeID>overview</homeID>
<mapref location="mindy.jhm"/>
</maps>
<view>
<name>TOC</name>
<label>overview</label>
<type>javax.help.TOCView</type>
<data>MINDYtoc.xml</data>
</view>
</helpset>
MINDYtoc.xml
<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<toc version="1.0">
<tocitem text="MINDY">
<tocitem target="overview" text="Overview"/>
</tocitem>
</toc>
mindy.jhm
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE map PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Map Version 1.0//EN"
"http://java.sun.com/products/javahelp/map_1_0.dtd">
<map version="1.0">
<mapID target="overview" url="mindy.HTML"/>
</map>
Example 2: Filtering Help Set - Multiple TOC entries
The filtering help set contains multiple TOC entries, making clearer the meaning of the various tags:
filterHelpSet.hs
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE helpset PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 1.0//EN"
"http://java.sun.com/products/javahelp/helpset_1_0.dtd">
<?TestTarget The help set file for the project tree component.?>
<helpset version="1.0">
<title>Filters</title>
<maps>
<homeID>overview</homeID>
<mapref location="filterMap.jhm"/>
</maps>
<view>
<name>TOC</name>
<label>Filters and normalizers</label>
<type>javax.help.TOCView</type>
<data>filtertoc.xml</data>
</view>
</helpset>
filtertoc.xml
<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<toc version="1.0">
<tocitem text="Filters">
<tocitem target="overview" text="Filters Overview"/>
<tocitem target="missing.value.filter" text="Missing Values Filter"/>
<tocitem target="single.value.filter" text="Affy Detection Filter"/>
<tocitem target="deviation.filter" text="Deviation Filter"/>
<tocitem target="expr.threshold.filter" text="Expression Threshold"/>
<tocitem target="two.channel.filter" text="Two Channel"/>
<tocitem target="Genepix.filter" text="Genepix Filter"/>
</tocitem>
</toc>
filterMap.jhm
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE map PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Map Version 1.0//EN"
"http://java.sun.com/products/javahelp/map_1_0.dtd">
<map version="1.0">
<mapID target="overview" url="Filters Overview.htm"/>
<mapID target="deviation.filter" url="Deviation Filter.htm"/>
<mapID target="expr.threshold.filter" url="ExprThreshold Filter.htm"/>
<mapID target="missing.value.filter" url="Missing Value Filter.HTML"/>
<mapID target="single.value.filter" url="Affy Detection Filter.HTML"/>
<mapID target="Genepix.filter" url="GenepixFilter.HTML"/>
<mapID target="two.channel.filter" url="TwoChannel.HTML"/>
</map>
Note for future development
The javahelp2.0 README file lists several different redistributable files. We currently include jhall.jar:
- javahelp/lib/jh.jar The standard library that includes everything needed to use the help viewer and the standard navigator types (TOC, index, full-text search).
- javahelp/lib/jhall.jar Includes all the JavaHelp system classes, including the tools required to create a search database.
- javahelp/lib/jhbasic.jar A subset of jhall.jar that does not include support for the full-text search engine. This subset might be useful for simple help systems that do not require a full-text search database or for help systems whose size is important.
- javahelp/lib/jhsearch.jar The default full-text search engine used in the JavaHelp system.
