What's covered?
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 topic has been written following a crash course in producing some JavaHelp. I do not have extensive experience of producing javahelp and prior to a recent 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.
I have written this topic partly to help others who may be placed in the same position and not have such help available to them and partly to remind me next time I have to produce some JavaHelp.
Before you go too far, I suggest you read Mike Hamilton's comments in Updates below.
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. I would STRONGLY recommend that you avoid JavaHelp 1.1.3, unless you really need to use it. In my experience, I found it was full of bugs, most notably that it would crash or hang when I tried to print a topic from within the JavaHelp output. JavaHelp 2.0 is much more stable. Secondly, I just tried building a 1.1.3 JavaHelp in my full version of RH X5 and got a fatal exception error both when I created compressed JavaHelp (which is what we use for JavaHelp 2.0) and uncompressed. I know I created JavaHelp 1.1.3 using a product called Helen, but I must not have built it using RoboHelp. Unfortunately, it looks like it's a flaw in RH. If you really, really need to build JavaHelp 1.1.3, look at Helen from Software7 (www.software7.biz). It's written in Java, is built for JavaHelp only and it allows you to build for 1.1.3 and 2.0. The only reason we're not using it now is that management didn't want to support a product that could only create one type of output. It has a good wizard to create a project, but it's more of an "assembly" tool - you create your topics outside of the program in HTML, then import them into Helen. My experience with support, even though they're in Germany, was outstanding. |
| 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. 1) RoboHelp Version: RoboHelp 5.0.2, Build 801. I have this installed in the default location: C:\Program Files\RoboHelp Office 2) Java SDK The 1.6 SDK didn't seem to work. So I stripped off all the Java installs from my machine (both SDK and JRE) and started from scratch with the 1.5 release. I downloaded the SDK from this URL: http://java.sun.com/javase/downloads/index_jdk5.jsp Choose the "JDK 5.0 Update 11 with NetBeans IDE 5.5" option. This installs the SDK, the JRE, and NetBeans (the IDE for Java). You probably won't use this as a tech writer, but it's there as part of the install, and won't hurt anything. One thing I did when installing the SDK and JavaBeans was to select a path that had no spaces in it (i.e., not in "Program Files"). Installs like this sometimes automatically update your path, but don't always manage spaces properly, so this was just to be safe. I used the default location for the JRE (runtime environment). Here's a cut and paste from my install dialog: J2SE Development Kit 5.0 Update 11 installation location: C:\Java\jdk1.5.0_11 J2SE Runtime Environment 5.0 Update 11 installation location: C:\Program Files\Java\jre1.5.0_11 NetBeans IDE 5.5 installation location: C:\Java\netbeans-5.5 3) JavaHelp You also have to have JavaHelp installed on your machine. JavaHelp 2.0 is kind of the baseline now, apparently (the previous release 1.1.3, was pretty limited). I downloaded JH2.0 from this link: http://java.sun.com/products/javahelp/index.jsp I put it at the same level as the Java SDK install: C:\Java\jh2.0 4) Environment Variables As Jim pointed out, you need to set the Environmental Variable "JHHOME". The value of that path should be the root directory for your JH install, so: - Right click on My Computer > Properties. - Choose Advanced > Environment Variables > System Variables - Check the value for JHHOME and make sure it matches the install dir. for JH (in my case, C:\Java\jh2.0) 5) Path The path variable tells the OS where to look for executables it can run. Edit that as Jim pointed out. Just for future reference. This was a bit painful, but mostly because I wasn't familiar with Java, but also the doc on the RH side was a bit deficient in guiding me toward a successful install. |
| 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: A) Java is nowhere near as cross-platform and headache free as is W3C compliant XHTML/DHTML. There are just too many variables such as what JRE is installed, who made the JRE, "oh, my app only runs in the Microsoft JRE, but not the Sun JRE" etc. B) When I was running the RoboHelp program we spent a HUGE amount of time and money supporting both JavaHelp and Oracle Help only to find that a super small percentage of the customer base (as in less than three percent) used either format. To make matters worse, that small group of users generated a huge amount of burden on the tech support staff. C) Sun and Oracle have really had a spotty, on again/off again track record for their own formats. It is tough to justify the dev hours for something the vendor themselves won't champion full time. D) Finally, the functionality just wasn't there. Most of the people who were absolutely begging for JavaHelp support were completely underwhelmed with the format once they were actually able to generate it. Most opted to switch to WebHelp for the better customer experience and the ability to brand the interface to match their product and their corporate look and feel (something difficult with the Java-based formats). Please note, I'm not saying that either JavaHelp or Oracle Help for Java are bad formats, just that we haven't seen enough demand to justify including them in Flare. In fact, we get more requests for formats like AppleHelp and Eclipse Help than we do for JavaHelp. We are always open to adding new output formats, in fact the next release of Flare includes several new output formats, we just have to see a business case for including them. If my phone suddenly started ringing off the hook with people asking for BobHelp, then we would research it and include it. |
Date |
Changes to this page |
| 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. |
