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:
- Context sensitive help isn't an option
- Generally the document is rather large
- 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.
Best Answer
If you're prepared to author your help in DocBook XML markup rather than HTML, DocBook has support for producing WebHelp: http://wiki.docbook.org/WebHelp
The WebHelp documentation is also a demo of the output: http://docbook.sourceforge.net/release/xsl/current/webhelp/docs/content/ch01.html
It gives you a Web-based HTML help format that includes: