![]() |
JavaHelp Basics |
![]() |
|
This page covers:
If you prefer to print and read this topic, click the Show All button and then use your browser's print function. The images are deliberately not scaled down so that you can see them without distortion.
This is an old topic that I will not be updating. However, JavaHelp is an old format so you may still find it useful. Please do note the caveats before you go too far.
This topic was written following a crash course in producing some JavaHelp. I do not have extensive experience of producing javahelp and prior to the request to produce some, I knew nothing of this area. I had to do some quick research but fortunately I work with some very good developers who eased the learning curve tremendously. I am grateful to Paul Symonds in particular for explaining the concepts and to Jon Hawkins for getting the necessary software working for me.
Before you go too far, I suggest you read Mike Hamilton's comments in Updates below. It is a poorly supported format and usually something else will do the job. There seems to be a misconception that for Java apps you have to have Java help.
Let's get this clarified first as it does cause some confusion for people new to this area.
This topic is about the help for an application written in Java.
Programs are written in Java as this enables the same code to be used on a variety of operating systems, Windows, Unix, Linux and Mac for starters. The way Java applications work also means that many of the usual rules about help do not apply here. For example, under Windows with XP Service Pack 2 applied, webhelp cannot easily be run if installed on the users hard disk. Such rules do not apply to Java applications. The best way it was described to me was that a Java application "can get under the covers" and it's down to the developer what can be done. Using a CHM file is an exception to the "rules" the developer can get around as a CHM file is reliant on files that will only be on a Windows operating system.
That means that there are three options for producing help for a java application.
Option |
About |
WebHelp |
You produce this in exactly the same way as you normally would. The rule about not running it from a hard disk under Windows XP Service Pack 2 does not apply. Anyway that's for the developer to worry about and I understand that it is not a major problem. I believe it is true to say that map ids cannot be used but that does not mean that context sensitive help cannot be provided. The developer has to call each topic by using its html file name. |
Compressed JavaHelp |
This packs the files used into a .JAR file which for our purposes is much like a winzip file. The developers can access the files they want from the .JAR file and display them in a javahelp viewer. |
Uncompressed JavaHelp |
This is similar to webhelp in that the files remain in a folder structure, are not compressed and are not packed into one file. Like compressed javahelp, it is viewed through a javahelp viewer which we will cover later. |
Which method you use will depend on several factors:
Before developing your help, I suggest you really need to sit down with the project and product managers to ensure they fully understand the differences between webhelp and javahelp and the differences between javahelp displayed in the Sun viewer and the Oracle viewer.
Click the links below to see the same topic displayed in various formats.
Click here to see webhelp
In this screenshot, everything displays exactly as you would expect. Note all the bullet points are clean and the table cells have a thin border.
Click here to see javahelp in the Sun viewer with no tweaks applied
See how the bullet points look like they are from MineSweeper and the table cell borders are wrong. Also note the appearance of the navigation pane.
Click here to see javahelp in the Sun viewer with tweaks applied
The right pointing arrow has been set up to work like a Lotus Notes twisty. When you click on it, the arrow will point down and show the topics available. For lower levels of book, there will be plus / minus signs which I don't think you can avoid.
Note that although I have got borders around the table cells by defining them in the style sheet, the appearance is not the same as in the webhelp.
Because the border is defined in the style sheet, it will affect all tables so I created a class to give more than one type of border. Nonetheless it still took a lot of tweaking to get rid of the border around the second set of bullet points. That tweaking would be necessary in all topics every time you generate. Not really viable unless you can make it work better. Using this viewer, I think you would end up deciding to accept no borders around table cells
.
Click here to see javahelp in the Oracle viewer with no tweaks applied.
Initially only the Navigator is displayed but note the familiar books and the cleaner appearance, with no tweaks. The user can double click a topic or highlight it and click the icon below File in the menu. A second window will then open alongside with the topic displayed. The two windows are easily docked if that is the user preference.
You can change the images in the navigator pane by following the method described for The Sun Viewer.
On screen, this second window will display alongside the navigator window.
After considering all the pros and cons of these methods, it is then up to the project manager to balance the impact of you having to learn / work with javahelp and any developer issues with the help format.
Javahelp has limitations as you have seen. In RoboHelp go the Help menu, click Contents and Index. In the index look for JavaHelp and then limitations. Be ready to scroll down the list!
The good news is that the Oracle viewer seems to handle them. For simplicity, in this topic I will assume that those of you still going with javahelp will persuade the powers that be to go with the Oracle viewer. If for some reason you are compelled to use the Sun viewer, there are some workarounds that are described later.
For the production of the topics, the index and the contents, I have written this topic assuming you are going to use RoboHelp but you can use other tools, you will need to amend the procedures. Anything I say about RoboHelp from hereon in this topic is based on RoboHelp HTML X5 although RoboHelp has supported javahelp since RoboHelp 2000.
You will need to download some resources from the Sun and Oracle sites. Speak to your IT people before installing any software.
The downloads come with documentation and / or online help. Do read these resources. They contain a lot of useful information from which I found the tweaks I describe. Many of the methods described in the Sun documentation also apply to Oracle and vice versa.
After you have downloaded and installed the Sun resources, you need to create some Environment Variables before installing the Oracle Help for Java. These can be set up as User Variables or System Variables. If that is meaningless, you may want to enlist the help of your IT people or a developer in undertaking these steps.
You need to decide which viewer is going to be used before starting production.
OK, if you did not have to click the link will be pleased to know you just work normally in RoboHelp. Create your bullet points as normal and create your tables as normal. Use your conditional text and as far as I could make out, any of the other features. They all work fine in the Oracle javahelp viewer.
Welcome back to those of you who had to sidestep and read up on the Sun viewer.
In RoboHelp Explorer, look under Single Source Layouts and see if there is a JavaHelp or Oracle output option already shown. If there is not, right click and select JavaHelp or Oracle from the list that will be displayed.
Start the wizard and go to the Output frame on the first page. Select one of the options for compression and the javahelp version you require. Everything covered in this topic is based on selecting the JavaHelp 2.0 options. Work through the wizard.
You will be able to see the output after generating it by right clicking the layout and selecting View.
You can also view the help by entering something like the following into the Run prompt.
hsviewer.jar -helpset D:\rh_javademo\all_outputs\uncompressed_oracle\rh_javademo.jar
hsviewer.jar -helpset D:\rh_javademo\all_outputs\uncompressed_oracle\rh_javademo.hs
I was only able to open this via RoboHelp. Not sure why.
Go to Start and Programs. Find Oracle Help for Java and run the viewer.
I hope you find this topic of some use in getting started with javahelp and would welcome any feedback.
May I again express my special thanks to Paul Symonds and Jon Hawkins without whose help I would not have been able to produce some javahelp for my employers or write this topic.
The topic shown in all the screenshots is contained in a RoboHelp HTML X5 project that you can download. That gives you the opportunity to try out what I have described and see how well you get on. Your developers may also find the outputs useful to test their side of the job.
It is not my intention to develop this topic further as I have no occasion to work with javahelp. However, I will add to this section any useful bits of information that I am sent. The information will be as sent to me, just edited for brevity and / or clarity.
Credit |
Information |
Kathy Hanten |
I have to use the Sun Viewer and one thing I had to mess with is any text that I made bold appeared to have extra spaces around it. After some research, I found that I had to replace the RH code of <span style="font-weight: bold;"> </span> with something like <b></b> or <strong></strong> and that made the extra spaces go away. |
Jim aka Maniac9999 |
I was scrolling through this folder and found your post. I don't know
if you found an answer to your problem, but here's my two cents. |
Greg Minter |
As promised, I wanted to post what my successful installation looked
like so that others might benefit. Unlike Jim suggested, I did not have
to uninstall RoboHelp, and I don't think that's necessary. It is, as he
suggested, just more important to get the Java install right and have the
path and env. variables set properly. |
Jim aka Maniac9999 |
In repsonse to another much later post Jim added this: Speaking of JavaHelp, I just found out over the last few weeks that RoboHelp 7 only supports JavaHelp 1.1.3, not JavaHelp 2.0, which is much more stable. I found this out after installing RH 7 and trying (and trying) to get it to build JavaHelp 2.0. I finally gave up and called Adobe Support. Adobe emailed me last week asking which JRE I used (1.5.0_06) and I'm hoping to get a reply soon. They also said they didn't have any plans for a future patch to get this to work, but there might be the possibility of me getting a DLL. Like you mentioned before, the authoring community for JavaHelp is probably tiny. |
Mike Hamilton |
In a post on HATT (7 Aug 08), Mike Hamilton explained the main reasons MadCap Software don't have a JavaHelp output in Flare and these include: |
Praful Jain |
Q-Term posted this problem: Since I am generating a context-sensitive help and my customer is only able to implement a help project based on JavaHelp 1.1.3, I cannot use JavaHelp 2.0, though there is a whole series of restrictions with JavaHelp 1.1.3. With RoboHelp v7, everything worked fine when creating a JavaHelp 1.1.3 project. With RoboHelp v8, however, the TOC is missing in the JavaHelp. It is not displayed. Usually, I am working on my main PC under Windows XP. I tried to generate a JavaHelp 1.1.3 version with RH 8 under Vista (which I have on my notebook), and the TOC was displayed. The project source is a Web Help project. When I copy the entire project with the generated JAR file to the PC with Windows XP installed, the TOC is not either displayed. Praful Jain responded with this: Each JavaHelp file has a helpset file with extension .hs. This HS file tells javahelp about the help file structure and where the TOC file, index file, and other information can be found. the problem lies in this .hs file itself. The problem line is <view mergetype="unite-append"> you need to change this line to <view mergetype="javax.help.UniteAppendMerge"> and now try running the javahelp again. You should be able to see the TOC, that's what I did to make TOC appear in javahelp. Better still, Praful then added this screenshot from RoboHelp 8 where you can select the JavaHelp version and that should make the code change for you. |
IMKarla2 |
Some information that may be useful at the end of this thread. |
If you find the information and tutorials on my site save you time figuring it out for yourself and help improve what you produce, please consider making a small donation.
Date |
Changes to this page |
06 Feb 2017 |
Topic reviewed. Caution added. Any screenshots may differ in your version of RoboHelp but the functionality is the same. |
18 Aug 2012 |
Link to IMKarla2's post added. |
10 Feb 2012 |
Updated with Praful Jain's response to a JavaHelp version problem. |
14 Aug 2008 |
Updated with a further comments from "Jim aka Maniac9999" and Mike Hamilton. |
04 May 2006 |
Updated with Greg Minter's RoboHelp forum post. |
27 May 2006 |
Snippets updated with information about version 1.1.3. |
26 Feb 2006 |
What tools do you need? amended to indicate you can use tools other than RoboHelp. |
07 Oct 2005 |
Snippets section added. |
12 Apr 2005 |
Updated to cover editing compressed javahelp and presenting javahelp via the native browser. |
10 Apr 2005 |
Major rewrite to add information about the Oracle javahelp viewer and to separate out the issues when using the Sun viewer for javahelp. |
05 Apr 2005 |
New topic. |