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