Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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.

share|improve this question
    
Whats wrong with using a standard tool like the browsers in build search mechanism. Users understand, it's significantly more battle tested then your custom search mechanism and the UI is more familiar to users then your search system –  Raynos Nov 7 '11 at 2:30
1  
@Raynos Browser-based help usually sucks pretty bad. The default help system in VS2010 is a good example of that. –  MetalMikester Nov 7 '11 at 11:28
add comment

6 Answers

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.

share|improve this answer
add comment

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).

share|improve this answer
add comment

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:

  • 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.
share|improve this answer
1  
That is basically what AsciiDoc does. –  bluebill Oct 30 '11 at 12:03
add comment

Sounds like jguery or something along the lines of this SE entry do what you want.

share|improve this answer
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
    
I was thinking along the lines of a javascript search engine. I will have to do some more research. –  bluebill Oct 23 '11 at 11:38
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.