A few feature requests and problems

Question

This mail is going to have several requests for improvement on the Oracle Help for Java platform. Lest anybody think I'm just complaining, let me say that in general I have been very happy with OHJ. We (ANSYS, Inc: http://www.ansys.com) use it as the online help system for a series of engineering simulation software products which we have been developing and marketing for over twenty years. We support about a dozen platforms and have a very large documentation set and OHJ is the only online help system we have encountered that gives us reasonable performance and the features we need. So far as we can tell, it is the best cross-platform online help system available.
That said, we have encountered a few minor problems which we would like to have addressed. I have already tried sending this to the support email address ([email protected], or something like that), but the mail is always returned with a message about internal lists not being available to outside users. (Another user complained about this in a prior thread)
1) We have two applications which run in tandem and access the same instance of OHJ. The documentation is contained in two different helpsets, and we want to keep the helpsets separate to the user, so we have set the combineBooks parameter to "false." When the user requests help, however, the Table of Contents pane is not updated to match the helpset in which they requested help. Could the showTopic(Book book, java.lang.String topicID) method be modified to call the showNavigatorWindow(Book activeBook) method if necessary? (i.e. if the navigator window is currently visible and set to a different book object)
2) Similarly, could the NavigatorWindow be updated if we follow a hyperlink into another book?
3) On the Windows platform, the Help window doesn't come to the top / gain focus when the user requests help for the first time
4) When using "dockedByDefault", the control over window size and position we had with the <wintype> tag is lost. That is, when docked, the window (navigator + content) always comes up in a fixed pixel by pixel dimension at the center of the screen. I use a high resolution screen, and the result is that I always have to resize the help window to read the content. I expect that some of our users will have similar high resolution screens. (we cater to the world of CAD). Could we have more control over the window size in docked mode, or at least have the default size relative to screen resolution in the same way we could set the wintype to 60% width and 60% height to fill a good portion of the user's screen?
5) Have the OHJ developers (or anyone else) looked closely at memory usage? I'm using up to 70MB of RAM for a run of the help system, and I'm just waiting for users' complaints on that one. I realize this is a trade-off that you often have to simply accept with Java-based technologies, and I'm not all that upset about it. However, if we could gain the user 10 or 20 more MB of RAM, that would be something.
6) Is there any way to combine some books and not others? (This is really grasping at straws. Feel free to simply say "no, and there never will be")
7) The documentation refers to the capability of customizing the toolbar for different wintypes. I haven't been able to do this for the default wintype.
The remaining few problems have to do with printing. These are really trivial issues from my point of view, as our official policy is that we don't support printing from the help system. (We provide PDF's of the manuals for people wanting hardcopy) However, they would still be nice to fix:
1) Printed hyperlink text often overlaps neighboring text
2) Ignoring background color when printing requires that we use media rules in our CSS. Could you ignore the background by default when printing?
3) In our Table of Contents, we have tree nodes that point to subheadings in a file, so it ends up that a single file will have multiple entries in the Table of Contents. When using the "Print Topics" feature, the entire file is printed for each of these nodes. Could the Print Topics feature keep track of which HTML files it prints, and print each one only once?
Again, I apologize for the many complaints (really suggestions) raised in this single post. These have been building up for a while, but between the previous state of this mailing list (completely overrun by people wanting general Java information) and the mail server errors at the only e-mail address I could find, this list just kept growing, based on our internal usage and testing. The truth is, I am very satisfied with OHJ, and am happy to find a cross-platform help system other than Sun's JavaHelp (which was way too slow for us last time I checked). Please consider this a detailed field test of OHJ 4.1.12.
Thanks for any help and attention to these concerns,
Jeff Beal
Documentation Tools Specialist
Ansys, Inc.

Answer 1

Wow, that's a lot! I have tried to answer all of your concerns. Here goes!
Problems with the mailing list
We're working on restoring the ability to send messages to our mailing list for external users. We'll post on this forum after we get that working again. Sorry about that.
1 and 2) Automatic switching of active book when showing topic
OHJ does not (by design) automatically switch the active book when a topic is displayed, whether it is from a CSH request or by following a link.
3) Help doesn't come to top
I cant reproduce this with OHJ 4.1.12 on Windows 2000. What OHJ and OS versions are you running? What options are you using on your Help object? Can you post some way to reproduce it?
4) dockedByDefault causes OHJ to ignore wintypes size
I reproduced the fact that OHJ ignores the wintypes size parameters when dockedByDefault is set to true. I have filed this as a bug; the height and width parameters should set the size of the content pane even if docked by default. The location parameters, on the other hand, are not supported when dockedByDefault.
5) Have the OHJ developers (or anyone else) looked closely at memory usage?
We certainly have looked closely at memory usage, but unfortunately this is not a problem with easy answers! :) Partially its due to the overhead Java imposes, and partially its a function of the size of your help contents metadata the number of entries you have in your keyword indices, TOCs, and (to a lesser degree) topic maps. So, the more you can remove entries from these files, the smaller OHJs memory footprint will be. (Note that you can have as many HTML files as you like; these dont stay in memory!)
6) Is there any way to combine some books and not others?
Sure. To combine books a.hs, b.hs and c.hs, you can create a master help set (master.hs) with these contents:
<helpset>
   . . . various helpset parameters here . . .
   <subhelpset location="a.hs" />
   <subhelpset location="b.hs" />
   <subhelpset location="c.hs" />
</helpset>Then instead of loading the books individually, just load master.hs.
See the docs for subhelpset in the Oracle Help guide at http://otn.oracle.com/ohguide/help.
7) Customizing the toolbar
Though we have documented syntax to support customizing the toolbar for a window type, OHJ does not currently implement this.
printing 1) Printed hyperlink text often overlaps neighboring text
This is an ICE problem, and we are waiting on a fix from them. Sorry about that. Out of curiosity, have you tried it on various printers/OSs/JDKs? Weve found some work better than others. Id be curious whether JDK 1.4 was any better.
printing 2) Ignoring background color when printing
You can disable printing background colors by doing the following in your code:
System.setProperty("ice.pilots.html4.printBackground", "false");
printing 3) Printing multiple copies of topics in same HTML file
Yep, this is a bug, and it is logged.
Thanks for all your comments, and were glad that you like the product.
-brian