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
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, deployed through Oracle Help for the Web.
OHW Configuration and Deployment
Which web servers should I use with OHW?
OHW requires a servlet engine that supports version 2.0 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:
- Oracle Containers for J2EE (OC4J) - supports Servlet 2.3
- Apache Tomcat - supports Servlet 2.3
- Apache JServ - supports Servlet 2.0
These servlet engines can be used directly or within a web server. If you are
using OHW with Oracle9iAS a supported version of OC4J is included.
What browsers support OHW?
Any standard HTML browser with JavaScript support.
How do I configure OHW with OC4J (Oracle Containers
for J2EE)?
The Demo Bundle that comes with the OHW release includes a sample OC4J configuration.
Use this as a model for your own configuration. For more details see the Deployment
section in the "Oracle Help for the Web Developer's Guide" chapter
of the Oracle Help Guide.
How do I configure OHW with Oracle9iAS?
Configurations in Oracle9iAS must be made through the Oracle Enterprise
Manager (OEM). The OEM Administrator can use OEM to edit the relevant OC4J configuration
files as well as deploy new versions of your help system.
Oracle9iAS requires that applications such as OHW be archived in .ear
files for deployment. The details of creating Ear files for OHW can be found
in the "Oracle Help for the Web Developer's Guide" chapter of the
Oracle Help Guide.
Oracle9iAS ships with the necessary OHW and UIX java class libraries
in the oc4j/j2ee/lib directory but each application must provide its own access
to these libraries through setting a classpath or library path variable.
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 oc4j/j2ee/home/config/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 oc4j/j2ee/home/applications/ohw-eapp/ohw/WEB-INF/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 OC4J 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 OC4J
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"
/>
While deploying OHW in Apache Tomcat I ran into
a problem with error message: The requested resource (/navigator) is not available.
How do I fix this?
Add a trailing slash to the URL that accesses OHW. If you are using the default
URL mappings, then use myserver/ohw/help/
instead of myserver/ohw/help.
Can I include my helpset in a Jar file?
Yes, Jar files will work for both OHW and OHJ following these 2 simple steps:
- Archive your entire helpset and control files into a Jar file (but do not
include ohwconfig.xml, the OHW configuration file)
- 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 :
- 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.
- 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 version 1.3.1 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
will be merged into the following table of contents
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=big5">
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.
| 
Bookmark