This page is a list of frequently asked questions with answers regarding Oracle Help Technologies and its two products - Oracle Help for the Web (OHW) and Oracle Help for Java (OHJ).
The answer depends on your application requirements. OHW is a web application based on a Java servlet. It is therefore the appropriate choice as a help system for other web applications. The easy access of a web application also makes OHW a good choice for a standalone hosted help system. OHW has minimal client software requirements while allocating heavy processing tasks to the server side.
OHJ is a Java client application that can also run as an applet. It is therefore an appropriate help system for Java clients and applets. OHJ also provides a utility for creating a full text search and an authoring wizard for creating helpset files for use in either OHJ or OHW.
Although most Oracle Help features are available on both products, it is good to check the product documentation if you have a specific feature in mind.
Downloads are available from the the Oracle Help Technologies section of the OTN (Oracle Technology Network) web site.
Contact firstname.lastname@example.org to obtain previous releases of Oracle Help technologies including legacy OHW UIX releases.
OHW requires a servlet engine that supports version 2.5 or later of the Java Servlet API as defined by Sun Microsystems (link). Recent versions of these servers of the following:
To change the base URL, edit the following line in http-web-site.xml to read as follows
<web-app application="ohw-eapp" name="ohw" root=" /myurl" ... />
To change the "/help/" appended at the end of the URL, edit the following line in web.xml
These changes will now produce a URL like the following:
Create two different application server web modules that will create URLs like this:
1. The first thing to do is to create two web modules under the same OHW application, found under j2ee/home/applications/OHW, as shown below.
j2ee/home/applications/OHW directory structure
¦ ¦ +---project_one
¦ ¦ +---project_two
2. Next, edit application.xml found in META-INF directory to define two web-modules, both within the same <application> element:
3. Then create a separate entry for each web site/url in j2ee/home/config/default-web-site.xml. These entries will be under the same <web-site> element
<web-app application="OHW" name="project_one" root="/project_one" />
<web-app application="OHW" name="project_two" root="/project_two" />
Yes, Jar files will work for both OHW and OHJ following these 2 simple steps:
<helpset jar="myapp/helpset.jar" location="myapp.hs">
You will need to set up your UNIX server to use the XServer correctly. For details, see the "X Server Configuration for Image Generation" chapter of the UIX Developer's Guide, which is included online as part of the Oracle9i JDeveloper help.
Yes, but you should be aware of the the following :
OHJ supports a pluggable HTMLBrowser interface (refer to JavaDoc specs). OHJ clients can specify the browser they want to use when they create the Help object. You have two options if you want to run OHJ from a browser :
First of all, the Java virtual machine (JDK or JRE) version should be one of the versions specified in the release notes. Currently Sun Microsystems Java SE 5.0 or higher is recommended.
Secondly, the necessary runtime libraries need to be in the classpath of the JVM.
Finally, if you are in authoring mode and using the indexer, then help-indexer-<version>Jar needs to be in the classpath. Other OHJ utilities, such as the authoring wizard, are found in the bin directory of the OHJ install. Their startup scripts already have the proper classpath set.
Under license from ICEsoft, Oracle has modified the ICEbrowser to support special features in Oracle Help. Other browsers will not support these features.
Unfortunately not. The ICEbrowser must first be modified substantially to support Oracle Help. Using the ICEbrowser without these changes will not work.
A test application called "helpsetDemo" is shipped with OHJ. A batch file to launch it can be found in the "bin" folder. On Windows platforms you may also launch this application from the Start Menu -- look for HelpSet Previewer off of Oracle Help for Java. The helpsetDemo will prompt you to enter the information for the book that you want to test.
One or more of the following is happening :
Oracle Help will support many file formats in their native formats without requiring a conversion. Oracle Help provides support for the following file types in their native format:
Oracle Help file formats for
|.hs||Oracle Help file format for helpsets.|
|.toc||Oracle Help table of contents (old version)|
|.tok||Oracle Help index (old version)|
|.hhc||MS HTML Help table of contents|
|.hhk||MS HTML Help index|
|.idx||Oracle Help Search Index|
OHJ files do not need to be converted. Both OHJ and OHW use the same file formats. To migrate a helpset from OHJ to OHW, all you need to do is to configure and deploy OHW as described in the Oracle Help Guide.
The indexer needs to be rerun. In order to catch the latest changes to the topic files, the indexer must be run as the last step before preparing a helpset for deployment.
These files are extraneous files that were in the directory when the indexer that was run but were not deployed. When the indexer is run, it will create an index from content text in all .htm/.html files in the target directory and all of its subdirectories.
Use the Japanese indexer that comes with OHJ. Typical syntax would be as follows:
Java -mx64m oracle.help.tools.index.JapaneseIndexer -e=MS932 D:\MyHTMLFiles myIndex.idx
where MS932 is the standard encoding of Japanese files authored on Windows systems.
Oracle Help can deploy multiple helpsets as a single merged helpset or as separate helpsets.
To merge helpsets, set the combineBooks parameter to " true". The same navigational views will then behave as if they were using a single, integrated helpset. For OHW, the combineBooks parameter is set in the <books> element; for OHJ, it is a parameter for the Help() constructor.
To use separate helpsets, set the combineBooks parameter to "false", then Oracle Help will automatically present a helpset switcher drop list for selecting the current helpset. All navigational views, including indexes, will work on the current helpset only.
The work is all done at runtime. No special build scripts or other preprocessing work is required.
The <label> element for all table of contents views must be the same. An empty or missing label will default to "Contents". It will not match a views whose label = "Contents".
Another way to correct this problem is to set useLabelInfo to "false". The label will then be ignored in merging, which will now be based on the <type> element only, so that all views of the same type will be merged.
For OHW, useLabelInfo is in the <books> element in the OHW configuration file (ohwconfig.xml). For OHJ, useLabelInfo is a parameter to the Help() constructor.
Yes. Oracle Help will merge helpsets whenever the <label> and <type> elements are the same for two or more <view> elements in different Hs (helpset) files. A merged keyword index will be sorted automatically according to the sort order of the user's language, while searches will be conducted across all of the merged helpsets.
Furthermore, Oracle Help for Java will merge the table of contents at the top level if the <title> element for the table of contents view is also the same. If another helpset has a different title, then another topic will be created in the table of contents. This feature is not implemented yet in Oracle Help for the Web.
For example, the table of contents for these 3 separately authored helpsets
will be merged into the following table of contents
These are the <title> elements in the SearchNavigator view for the individual helpset where this link is found.
Use the Oracle Help topicid protocol instead of a regular hyperlink. For example, consider a.htm in helpset1.jar that has a link to b.htm in helpset2.jar. The hyperlink should look like this:
where topicb is defined in the map.xml file as:
<mapID target="Here is topic b" url="b.htm" />
A regular hyperlink like <a href="b.htm"> will only work if a.htm and b.htm are included in the same Jar file.
HelpManager is a helper class to organize your help related code. It provides some nice features like F1 help and right-mouse click help. Refer to the Oracle Help for Java Developer's Guide for more information.
HTMLBrowser is an interface defined by OHJ. HTMLBrowser class is primarily used for displaying the help topics. OHJ gives you the flexibility to choose the browser you want for displaying HTML. OHJ comes with ICEBrowser as the default browser but you can use the underlying web browser when running as an applet.
You should create a new class that acts as glue between OHJ and the third party browser. This glue class will implement the HTMLBrowser interface and translate the calls between OHJ and the HTML component.
Yes, but only when running as an applet. Use the help constructor that takes AppletContext as the argument.
First, place the translated help in separate directories for each language. The directory name should be the ISO 639 language code for each language, such as "en" for English, "fr" for French, and "ja" for Japanese. If you are providing multiple dialects of the same language, then set one language as a base language, and then add the ISO 3166 country code for other versions. For example, you might set up Portuguese as "pt" for Iberian Portuguese and "pt_BR" for Brazilian Portuguese. Additional variation is also possible for regional variations within a country as a third element.
If you wish to jar up the helpsets, you can either create a separate jar for each language or a single jar for all languages after creating the language directory.
Finally the application needs to identify the user's base location, locale and helpset name in the URL. This is explained in the JavaDoc for oracle.help.common.util.LocaleUtils.
At runtime, Oracle Help will look for the user's preferred language and country and, if not found, it will fall back first to the base language and then to the default language, if necessary. This is essentially the Java locale lookup mechanism.
You will need to set up separate web applications (servlets) for each language. Each web application will have its own version of the OHW servlet and its own ohwconfig.xml file. The <locale> element in the ohwconfig.xml will identify the Java locale that OHW instance is running in. The user will be directed to the correct language based on the URL for that web application. A web application requesting help could dynamically create the link to the help system using the web application locale (if the application has that concept) or the HTTP request locale.
The encoding for the HTML files should be included in the file itself, using syntax like this in the case of the Big5 encoding used for Traditional Chinese:
<meta http-equiv=Content-Type CONTENT="text/html;charset=utf-8">
The encoding of the control files is set in the Help.setHelpEncoding method for OHJ or the <controlFileEncoding> element of the ohwconfig.xml file for OHW.
Yes, user interface strings for 30 languages are provided.
Oracle Help for Java includes the translated resources in help-nls-<version>Jar Make sure this file is in the classpath when OHJ is launched. Oracle Help for the Web includes the translations inside ohw.jar, which is loaded whenever OHW is started.