United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...

Oracle Help - Frequently Asked Questions

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).

General Questions

OHW Configuration and Deployment

OHJ Configuration and Deployment

Authoring

Navigational Views

Development Kit

Internationalization and Localization

General Questions

Should I use Oracle Help for the Web (OHW) or 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.

Where can I get OHJ and OHW?

Downloads are available from the the Oracle Help Technologies section of the OTN (Oracle Technology Network) web site.

How do I get support for Oracle Help?

Use the Discussion Form associated with this FAQ. Additional information is also available at the Oracle Help Technologies section of OTN. Click here to see the Oracle Help Guide.

How do I get prior a prior release of Oracle Help including OHW UIX?

Contact ohinfo_us@oracle.com to obtain previous releases of Oracle Help technologies including legacy OHW UIX releases.

OHW Configuration and Deployment

Which web servers should I use with OHW?

OHW requires a servlet engine that supports version 2.5 or later of the Java Servlet API as defined by Sun Microsystems ( http://java.sun.com/products/servlet/). Recent versions of these servers of the following:

What browsers support OHW?

How do I change the URL from the URL used in the OHW demo bundle?

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

<url-pattern>/ myhelp/*</URL-pattern>

These changes will now produce a URL like the following:

http"//mycompany.com:port/ myurl/myhelp/

I have a single instance of OHW but want to provide separate URLs for each  helpset. How do I do this?

Create two different application server web modules that will create URLs like this:

mywebsite.com/project_one/help
mywebsite.com/project_two/help

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
================================================
+---META-INF

+---project_one
¦ +---cabo
¦ +---helpsets
¦ ¦ +---project_one
¦ +---jsLibs
¦ +---WEB-INF
¦ +---lib

+---project_two
¦ +---cabo
¦ +---helpsets
¦ ¦ +---project_two
¦ +---jsLibs
¦ +---WEB-INF
¦ +---lib

2. Next, edit application.xml found in META-INF directory to define two web-modules, both within the same <application> element:

j2ee/home/applications/OHW/META-INF/application.xml
======================================================
<module>
<web>
<web-uri>project_one</web-uri>
<context-root>/</context-root>
</web>
</module>

<module>
<web>
<web-uri>project_two</web-uri>
<context-root>/</context-root>
</web>
</module>

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

j2ee/home/config/default-web-site.xml
======================================================================
<web-app application="OHW" name="project_one" root="/project_one" />
<web-app application="OHW" name="project_two" root="/project_two" />

Can I include my helpset in a Jar file?

Yes, Jar files will work for both OHW and OHJ following these 2 simple steps:

  1. Archive your entire helpset and control files into a Jar file (but do not include ohwconfig.xml, the OHW configuration file)
  2. For OHW, edit ohwconfig.xml to indicate that the source of the Jar file is a helpset.

    <helpset jar="myapp/helpset.jar" location="myapp.hs">

I have installed OHW on a UNIX machine and see my help content fine. However, the buttons and tabs have a degraded appearance compared to what I see on a Windows machine. How do I correct this?

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.

OHJ Configuration and Deployment

Can I run OHJ from a web browser?

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 :

  1. We recommend you use ICEBrowser as the HTMLBrowser. The ICEBrowser provides features such as popups, associative links, and author-defined window types that are not provided with other browsers.
  2. OHJ also supports using the underlying web browser such as Internet Explorer or Netscape Communicator for displaying HTML files. In this case, OHJ is running as a Java applet and you should use the Help() constructor that takes AppletContext as a parameter.

What Java configuration is needed to run OHJ?

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.

  • help-<version>Jar
  • ohj-jewt-<version>Jar
  • oracle_ice-<version>Jar
  • swingall.jar
  • help-nls-<version>Jar (if translations supplied with Oracle Help are used)

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.

Why is the ICEbrowser used as the default browser component in OHJ?

Under license from ICEsoft, Oracle has modified the ICEbrowser to support special features in Oracle Help. Other browsers will not support these features.

Can I use the more recent version of the ICEbrowser that is available from ICEsoft?

Unfortunately not. The ICEbrowser must first be modified substantially to support Oracle Help. Using the ICEbrowser without these changes will not work.

Authoring

How can I test my documentation in stand-alone mode?

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.

When I run the authoring tools from command-prompt, I get "Can't find class ...." error. How can I fix this?

One or more of the following is happening :

  • Your CLASSPATH is missing the OHJ related jar files.
  • The location of OHJ jar files in your CLASSPATH is incorrect. This could happen when you move the help install folder but forget to update your CLASSPATH.
  • If you are using the batch file to run the wizards, then you might have installed a newer version of JDK and deleted the JDK using which you installed OHJ. You need to update the batch files to use the new JDK in this case. You should do the same if you move the JDK folder to a different location; this is because the JDK paths are hardcoded into the batch files at installation time

How do I convert help files created in other authoring systems to Oracle Help format?

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:

File Type Description
.xml

Oracle Help file formats for

  • Map File
  • Table of Contents File
  • Index File
  • Link File
.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

Notes:

  • Support for Xml and Hs file formats includes support for the JavaHelp file formats as well. Differences are documented in the "File Formats" section of the Oracle Help Guide.
  • The Link File and Search Index file formats are unique to Oracle Help and can not be generated by other authoring systems.

I have an existing OHJ helpset. How to I convert the files to OHW format?

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.

Navigational Views

Why is my search index not updated properly?

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.

Why does my search index point to nonexistent files?

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.

How do I create a search index for Japanese?

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.

Why aren't topicid links, popups, or associative links working in OHW?

These features are implemented through JavaScript in OHW. Either set your browser to enable JavaScript or update your browser to one that supports JavaScript.

How do I set up Oracle Help for the Web to deploy multiple helpsets.

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.

I merge my helpsets and end up with two separate tabs for Contents. How do I make sure that a single tab is used?

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.

I have a large helpset that I want to distribute among multiple writers and then merge at runtime. Can I do this with Oracle Help?

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

  • TitleA
    • 1.1
    • 1.2
  • TitleA
    • 1.3
    • 1.4
  • TitleB
    • 2.0

will be merged into the following table of contents

  • TitleA
    • 1.1
    • 1.2
    • 1.3
    • 1.4
  • TitleB
    • 2.0

After I run a search, all items in my result set are followed by tags like "Source: Welcome" and "Source: Glossary". Where does this information come from?

These are the <title> elements in the SearchNavigator view for the individual helpset where this link is found.

How do I link between topics in two different . jar files?

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:

<a href="topicid:topicb">

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.

Development Kit

What is the CSHManager class for? Should I be using it?

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.

What is a HTMLBrowser in OHJ? Where is it used?

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.

How do I use a third party HTML component as my HTMLBrowser ?

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.

Can users user their own web browser as the HTMLBrowser in OHJ?

Yes, but only when running as an applet. Use the help constructor that takes AppletContext as the argument.

Internationalization and Localization

How do I set up Oracle Help for Java to provide translated help systems?

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.

How do I set up Oracle Help for the Web to provide translated help systems?

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.

My help topics and control files have been translated into languages with non-ASCII characters. How do I set up Oracle Help to display these characters correctly?

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.

Does Oracle Help provide translations of the Oracle Help UI?

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.

Left Curve
Popular Downloads
 Right Curve
Untitled Document