Alternativates to HTML Help

Question

We currently use a system called AsciiDoc which allows us to create documentation in a simple text markup. From that we can generate multiple output formats. We only make use of the pdf output and chm output formats.

I was wondering if there was an alternative to chm? What I am looking for is something that can be used off-line (this is important because quite a few of our users are in very remote places) with our software. It should have an index (it can be as simple as an html page with hyperlinked terms), it should be searchable and it should have a mechanism that allows specific entries to be called up from the code (similar to context sensitive help).

The two things that are against PDF in this case is:

1. Context sensitive help isn't an option
2. Generally the document is rather large
3. PDF is more suitable to printed documentation than context sensitive help

What I would like is to use html. The only problem with html is that I can't seem to figure out how to automatically provide a keyword search (other than the browsers ctrl+f functionality - I would like something more apparent). I also can't seem to find a method to automatically generate a hyperlinked index of key words. Context sensitive help would be simple because of the section tags - I could simply pass the url of the page and section that I am interested into the default browser and that page should load up to the correct section.

My requirements sound an awful lot like chm - they do. I modeled my requirements off chm. The only reason I don't like chm is because of the way the code interacts with it using mapids and such. I would much rather use store a plain text list (that is automatically generated for me) that my code can use to access the context sensitive portion of the documentation.

I am envisioning a script that would go through the html output files and generate an index page that simply contains a list of keywords that it found. obviously there should be word exclusion mechanism to ignore words like: the, it, is, etc.. This part would be relatively easy to write. The second part would need a script of some sort to put together a database of keywords and their location within the html text. I think this would be the tricky part along with providing the search mechanism within the browser.

Any ideas on alternatives would be appreciated. I would love to use a wiki or set of static html pages hosted on a webserver somewhere, but we have a critical offline usage requirement. Simply placing the html on the local drive doesn't provide us with the search requirements that we need.

EDIT:

I design software that is used by the mining industry. A lot of mines are very remote and do not have access to the internet in any meaningful way. There is nothing wrong with pdf or html or chm (except that it is getting old). If I could display a pdf file at the correct location (i.e. context sensitive help) I would use it. I am almost tempted to write my own - basically it would be a portable wiki. Speaking of that, if you suggest portable wiki - you have to think of the end user which may have no experience in using such tools. It has to be dead simple. That was the beauty of chm, it is a pain to work with but the end users like it.

Answer 1

The creators of RoboHelp went on to other things, and have come back around to make a better alternative. Check out MadCap's Flare - it supports a variety of output formats, generates an index, and supplies a search function that operates locally (via JavaScript).

Answer 2

If you're prepared to author your help in DocBook XML markup rather than HTML, DocBook has support for producing WebHelp.

The WebHelp documentation is also a demo of the output: http://docbook.sourceforge.net/release/xsl/current/webhelp/docs/

It gives you a Web-based HTML help format that includes:

• Full text search with:
• Stemming support for English, French, and German. Stemming support can be added for other languages by implementing a stemmer.
• Support for Chinese, Japanese, and Korean using code from the Lucene search engine.
• Search highlighting that shows where the searched for term appears in the results.
• Search results can include brief descriptions of the target.
• Table of contents pane with collapsible TOC tree.
• Auto-synchronization of content pane and TOC.
• TOC and search pane implemented without the use of a frameset.
• An Ant build.xml file to generate output.

Answer 3

We've been using Adobe RoboHelp to generate various styles of offline help documentation. It provides many output and integration options for content. The great thing about this tool is you can hand it to non developers and get great content with little effort integrates into your solution.

Answer 4

CHM itself is getting old, and Microsoft has also moved on to newer things: http://msdn.microsoft.com/en-us/library/bb164608(v=vs.80).aspx

But if you really want to avoid converting your help to an existing system, and are looking how to provide a search and keyword-lookup on static help files, here are two idea's:

• add a small localhost-only HTTP server to the project to serve a website with the documentation. Problems are when or how to start/stop this HTTP server and/or keep it running. An alternative would be implementing a custom URL scheme, but this would tie you to one browser and is a lot more work (and I can tell)

• write a JavaScript search engine. JavaScript in any browser is getting pretty fast and performant these days. A keyword index could be easily stored on JSON, and I have run regular expressons on local files with pretty good results.

Answer 5

What I am looking for is something that can be used off-line (this is important because quite a few of our users are in very remote places) with our software.

We use RoboHelp at my company and we good luck making the help files available offline as we often have users going from areas with network access to areas without.

It should be searchable and it should have a mechanism that allows specific entries to be called up

We use some pages in RoboHelp to explain the use of certain fields on a screen. We are able to have pop-ups for those fields that appear after a click. RoboHelp also has a very nice search ability and auto-generated index. I've always had good luck searching with it. This might not be a huge concern for you, but we are able to have anyone update the documentation because RoboHelp is a fairly easy program to use.