Eclipse Help as a Model

Self on Help

Thoughts from the OASIS DITA Help Subcommittee Chair

Blog entry: Submitted by tself on Mon, 2008-01-14 13:04.

In thinking about what a standalone (as in "not embedded UA") Help system generated from DITA source should look like, and what features it might have, Eclipse Help keeps cropping up. If a tech writer currently wants to generate an Eclipse Help system for distribution with a locally-installed application, the technical hurdles are quite high. It might not be an issue if the application is Eclipse-based, but it otherwise requires quite some overhead. In fact, I would imagine that it would be next to impossible to convince the developers to distribute the Eclipse runtimes just for the Help.

Eclipse Help is nonetheless extremely interesting as a case study of how a fully-featured Help system can be delivered, and could be used as a model or benchmark for cross-platform Help.

tself's blog
Login to post comments
8131 reads

I am an information developer who is starting the process of working with developers to deploy stand-alone Eclipse Help generated from XML source. I have some questions I hope someone who has been through this process can answer. 1) How is licensing handled for distribution?, 2) Our application is already running Tomcat. Is it possible to get it running inside that Tomcat instance? 3) What other technical hurdles did you need to address?

Hello,

1) It's an open source license. You should be able to distribute as much as you like.

2) Eclipse Help 3.2 and earlier uses it's own enbedded version of Tomcat. It's not configureable. For 3.3 and later the Help System uses the Equinox HTTP and Jetty that it shipped with Eclipse.

Eric

I'm not familiar enough with Eclipse Help to be able to answer Heather's question. Can anyone else help?

I agree that Eclipse is a great model for help. I'm disappointed that it would be difficult to implement for non-Eclipse apps. I'll be meeting in a couple weeks with our developers (I'm at tech writer) on how best to deliver help for windows-based applications. HTML Help is the default format, but it has limitations. I am hoping to get the developers to research and evaluate Eclipse as an option. Should I just send them to the Eclipse site or are there other additional resources that would help them evaluate Eclipse for our applications?

It's not that difficulty to setup a standalone Eclipse Help system, it's just that it could be easier :)

For technical documentation, I'd see the help document on how to actually do a standalone Eclipse server. Here's a general article to help you get started with Eclipse help content.

Eclipse Help is widely used. For example, in IBM, the majority of products, Eclipse-based or not, ship with the Eclipse help system. It provides a nice way to unify your help documentation.

Good luck!

Funny that this comes up. Eclipse just created a new "feature" to make it easier to use help standalone and especially in RCP-based applications. See bug 202160 for more information.

I believe the Eclipse User Assistance team is also working on a standalone download of the Help system on bug 202729 if you're interested in voicing your support.

Everything's relative. For anyone who doesn't understand the terms plug-ins, RCP, Jetty stacks, deployment, distribution, org.eclipse.help.standalone.Help, classes, etc, working out how to set up a standalone Eclipse Help system is essentially impossible. To me, easy means being able to run a one-click installation program. Or maybe a simple wizard. If it's more difficult than that, people will seek an alternative to Eclipse Help. Again, I'm not trying to bag Eclipse, and the great work of the Eclipse team - just trying to add some constructive criticism. I'd love the barriers to using Eclipse help to be lowered!

Yes, there is no one-click install for Eclipse Help.

However, my argument would be that a company from the wonderful Eclipse ecosystem would step-up and offer some services around Eclipse help or even a one-click installer for an Eclipse-help based system. Or another option is a wonderful contributor would step-up and give some patches to help this one-click install become a reality :)