WebHelp

Update: DocBook WebHelp Version 0.9/Beta release end notes can be found here: DocBook WebHelp Project

This is the design and planning page for the GSOC 2010 WebHelp project.

* Current progress/Demonstration of the WebHelp can be found at http://www.thingbag.net/docbook/gsoc2010/doc/content/ch01.html. The source code is maintained at DocBook repository: http://docbook.svn.sourceforge.net/viewvc/docbook/branches/webhelp/xsl/webhelp/

Student: Kasun Gajasinghe (http://kasunbg.blogspot.com)

Mentor: David Cramer

Abstract

DocBook is a set of standards and tools for technical documentation. A vital requirement for technical publications is to produce a Web-based help format that is synchronized with the content. So the documentation is up-to-date making site maintenance easier. This will contain client-side searching with support for stemming, table of contents, Index and a HTML export ability. The main idea is to generate a WebHelp Output from the DocBook content XML files.

Schedule (Updated on 29th May, 2010)

This is the the schedule as of 29th May, 2010, updated based on the WebHelp draft proposal.

• Bonding Period:
  • ...
  • Agree on and set up initial build environment
• First Half:
  • Develop the TOC tree using a standard CSS/JS-based mechanism (e.g. YUI).
  • Implement the synchronization of the TOC with the content and deep linking support.
  • Design client-side search improvments: stemming, internationalization, and lemmatization

  • Create an ant script or makefile to build a DocBook file as WebHelp, run the search indexer on it, copy required JavaScript and CSS files into place, etc.

  • Post demo of output and request feedback from the DocBook community.

  • Commit the functioning TOC, build script, and existing search functionality into a subversion branch in the DocBook repository and begin incorporating into the DocBook makefile (on the branch).

• Mid-term evaluations (July 12-16)
• Second Half:
  • Implement client-side search improvements:
    • Stemming mechanism (internationalized)
    • Asian languages
    • Lemmatization (internationalized)
  • Add search highlighting (such that the stem is highlighted in any word that matches in the content pane)
  • Create test plan and test all features of the solution.
  • Document use of the ant script and XSLS customization for the stylesheet user.

  • Make any necessary refinements to the DocBook makefile modifications.

  • Document maintenance of the XSL customization and indexer for the DocBook developer.

• Final evaluation deadline (August 20)

Fixes needed for the prototype's installation procedure:

Prototype is at: Web-based Help from DocBook XML Readme

• In addition to editing xsl/driver.xsl in Step 3 (of prototype), users have to edit build.properties to modify the xslt-processor and docbookx.dtd paths.
• Step 4 says to test the package by running 'ant doc'. That doesn't work: no target named doc exists in build.xml. Running 'ant webhelp', per Step 6, works fine at this point.

Update

29th May, 2010: The WebHelp will be developed on a CSS-based mechanism rather than a traditional frame-set approach. As of today, I developed the Table of Content pane using TreeView plugin of jQuery. Evaluated possibilities of using YUI and another jQuery plug-in. jQuery provides the persistence with use of cookies, such that the opened nodes of the tree are persisted between pages.

26th June, 2010: Did XSL customizations for WebHelp. The customization will be named webhelp.xsl. Created an ant script to build the DocBook file and to run the indexer. Implemented Table Of Contents (TOC) tree by use of jQuery, and it is synchronized with the content pane.

20th August, 2010: Project is completed. Further details can be found at README. End notes are at: DocBook WebHelp Project