August 16, 2011

DocBook to WebHelp - Better HTML Books

One of the projects the DocBook community sponsored for the 2010 Google Summer of Code was DocBook WebHelp. The goal was to develop a process for generating output that resembled WebHelp from DocBook. It resulted in a process that generated HTML output that uses jQuery to create a collapsible TOC and Apache Lucene to create a full text search index. It is slick.
The FuseSource documentation had been using HTML frames to accomplish something similar since we were part of IONA. While it looked good and got the job done, it was not a great solution. Some people complained that the frames didn't work in their browsers. We got complaints that it was hard to bookmark pages or to get links to send in e-mail. There were also complaints that the documentation looked very 1999.
So, a few months ago I started looking at what it would take to modify the FuseSource HTML publication process to use the DocBook WebHelp tools. It took a little doing because we have a pretty hefty customization layer, but all in all it was pretty easy. The guys on the DocBook mailing list were very helpful.
We started rolling out the new templates with the Fuse IDE 2.0 documentation . In the coming months the template will be rolled out across all of the FuseSource documentation.
The new WebHelp based HTML output is pretty slick. We added Disqus powered comment forms as well. They are not perfect, but incremental change is the name of the game. As we get feedback from customers, we will work to make them perfect.

8 comments:

  1. You're right about the WebHelp format. It looks great. We've been using it at our company for a few months. However, we find it's very slow to build. Don't know if that's a symptom of the fact that it was sort of shoe-horned in to the DocBook XSL build system. Must check out Disqus.

    ReplyDelete
  2. Eric,
    Glad you liked it. And, FUSE customization looks great.
    We've lately merged search indexer improvements from the code donated by oXygen. You might be interested to check it out as well.

    We are hoping to have a another round of feature additions in the next few months. So, if you have need anything to see in WebHelp let us know!

    ReplyDelete
  3. Hi Eric,
    I like what you've done with webhelp. The print button (which I assume uses a special print-oriented css) is a nice idea and one I've been meaning to add.

    I notice that the search is currently not working and that the js files for the search functionality aren't where your pages expect them to be. E.g.

    http://fusesource.com/docs/ide/2.0/user_guide/search/htmlFileInfoList.js

    Perhaps something got moved out of place on your web server?

    David

    ReplyDelete
  4. I forgot to add logic to the build system to copy the search indexes. It should be fixed now.

    ReplyDelete
  5. I'm trying to do webhelp from docbook on Ubuntu 12.04. I'm fairly new to the whole Linux writing experience, as I worked on Windows for a long time, and use the excellent tool MadCap Flare to generate PDFs and online help, single-sourced from one set of XML doc files.

    I've been able to generate PDFs that look okay, but I'm having trouble figuring out how to get the a two-paned online help format. I downloaded Kasun's zip, but it isn't working.

    Has anyone produced decent-looking two-paned online help on Ubuntu, from docbook source files?

    ReplyDelete
  6. Hi Scott,
    Are you using the most recent DocBook xsl distribution from SourceForge?

    http://docbook.sourceforge.net/

    The output should look like so:

    http://docbook.sourceforge.net/release/xsl/current/webhelp/docs/

    If you have specific questions, I'd suggest you ask them on the docbook-apps mailing list:

    http://wiki.docbook.org/DocBookAppsMailingList

    Or perhaps on the IRC channel:

    http://wiki.docbook.org/DocBookIrcChannel

    David

    ReplyDelete
  7. We are using the latest version of the style sheets from SourceForge with a custom Ant file to manage some of the extra copying bits for our content.

    ReplyDelete