Java man pages

As the holidays draw to a close, I've been trying out a few more ideas.

Solaris comes with man pages in nroff or sgml format, that can be preformatted and indexed with catman. (Why the preformatted man pages and index aren't created by default is beyond me.) But there are still a couple of weaknesses with the man system

• There's no search system
• There's no way to follow cross-references

The Documentation DVD includes html formatted man pages which have the linking element, which is an improvement. But this doesn't solve the search problem.

However, Solaris comes with Javahelp. So I had a little play today with creating a Javahelp helpset out of the html manpages.

This worked reasonably well, up to a point. It was pretty easy to knock up the helpset file, and the map, TOC, and index files, and to create a full-text database for searching.

The Javahelp hsviewer did a reasonable job of providing a user interface. You can navigate, and the search isn't too bad.

Where it all fell down was that the html display in the viewer uses the swing JEditorPane. Which is - shall we say - a bit primitive. So while the overall solution functions reasonably well, the actual display looks pretty awful. Sufficiently bad, in fact, that it's not going to work in practice.

So the idea that I could produce something from a quick hack came to nothing.

I'm not done yet, though. As I see it, there are 3 ways to go forward:

• Recreate the html versions of the man pages with an old html syntax that the javahelp display engine is going to cope with.
• Use a different html renderer component.
• Integrate this into a web server that does the searching so you do the search and indexing in a servlet but just shove the html pages out to a browser.

At the moment, the first looks the most attractive, as this also solves the problem of what to do with other man pages that you might have.