RamHelp ©

RamHelp is a tiny Java + XML Based help utility that creates a simple Help dialog based on an XML File.

Requirements to run RamHelp

  1. Sun JDK 1.3 or higher & JRE 1.3                                                  
  2. dom4j - The XML parser API from Apache (Get It)                     
  3. sax parser - (The required API is bundled along with this tool itself)


The RamHelp user interface is a similar to any traditional Help window with a tree view holding the contents sorted chapter wise and a HTML Editor to view the corresponding HTML file that holds the help information.
The user interface is built using a utility class called HelpXML, that needs an XML document as a parameter.(Alternatively, the HelpXML class also takes a string as parameter, that represents the path of the XML File.)

The RamHelp XML Structure

The RamHelp XML document has the following elements in that order. (validated by HelpDTD.dtd available : online at http:\\www28.brinkster.com\rsramanujam) (A copy has been provided along with the RamHelp package as well).

<HELP>
    <INFO>
        <AUTHOR> </AUTHOR>
        <TITLE> </TITLE>
        <DATE> </DATE>
        <VERSION> </VERSION>
        <COMMENTS> </COMMENTS> (OPTIONAL)
    </INFO>
    <CONTENTS>
        <CONTENT NAME="" URL="" CHAPTER=""> </CONTENT> (1 or more)
    </CONTENTS>
    <CHAPTERS>
        <NAME> </NAME>
    </CHAPTERS>
    <SEARCH> (OPTIONAL)
        <CRITERIA NAME="" CONTENT="" CHAPTER=""> (1 or more) </CRITERIA>
    </SEARCH>
<HELP>

The XML File's structuring is done based on the following assumptions.

  • Each Help consists of Contents
  • A set of contents can be grouped as a chapter

For example, If the Help title is Java, then we can organize the chapters as follows.

  • Java

    1. Introduction to Java

    2. The Green Project

    3. The creators

    4. The Features of Java

    5. The advantages of Java

    6. Data types in Java

    7. Blah

    8. Blah

    9. Blah

The XML file starts by defining the Information(The INFO Tag) about the help by way of its title and then
contains information on the author, the version of the help documents and the date of creation.

Next comes the CONTENT Tag that defines the Contents of the help. The INFO Tag has 3 attributes.
  1. NAME = The Title of the Content
  2. URL = The path of the HTML document for the topic.
    (note :this must be a fully qualified URL like file:pathname or http:\\pathname)
  3. CHAPTER = The Chapter to which this content belongs.
There can be one or more contents.

The CHAPTERS Tag comes after the INFO Tag and houses a NAME tag.
This NAME tag contains the Name of each chapter.
note :The NAME tag must hold only Chapter names that are present as part of the CONTENT tag's CHAPTER attribute

Then comes the Optional SEARCH Tag that in turn holds a CRITERIA Tag. The CRITERIA Tag has 3 attributes
The CRITERIA Tag has 3 attributes.
  1. NAME = The Search Term
  2. CONTENT = The Name of the CONTENT where this Search Term is present
  3. CHAPTER = The Chapter in which this Search Term is present.

The Search Tag is, however optional and internally, a Search is made
by trying to match the search text entered with the contents specified.

Unlike in any professional help tool, the Search results do not directly link you to the contents. However, a search result dialog will contain one or more statements in the format
'Criteria Name' is available in topic 'Content Name' of chapter 'Chapter Name;

That should direct the user to which chapter he needs to get into and under that which topic to look for.

A Sample XML file

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE HELP SYSTEM "HelpDTD.dtd">
    <HELP>
         <INFO>
             <AUTHOR>R S Ramanujam</AUTHOR>
             <TITLE>Java Doc using RamHelp</TITLE>
             <DATE>22/Nov/2001</DATE>
             <VERSION>1.0</VERSION>
        </INFO>
         <CONTENTS>
             <CONTENT NAME="JDialog" URL="file:..\javax\swing\JDialog.html" CHAPTER="Swing Docs"/>
             <CONTENT NAME="JFrame" URL="file:..\javax\swing\JFrame.html" CHAPTER="Swing Docs"/>
             <CONTENT NAME="JTable" URL="file:..\javax\swing\JTable.html" CHAPTER="Swing Docs"/>
         </CONTENTS>
         <CHAPTERS>
             <NAME>Swing Docs</NAME>
         </CHAPTERS>
         <SEARCH>
             <CRITERIA NAME="J" CONTENT="JDialog" CHAPTER="Swing Docs"></CRITERIA>
             <CRITERIA NAME="J" CONTENT="JFrame" CHAPTER="Swing Docs"></CRITERIA>
             <CRITERIA NAME="J" CONTENT="JTable" CHAPTER="Swing Docs"></CRITERIA>
             <CRITERIA NAME="j" CONTENT="JDialog" CHAPTER="Swing Docs"></CRITERIA>
             <CRITERIA NAME="j" CONTENT="JFrame" CHAPTER="Swing Docs"></CRITERIA>
             <CRITERIA NAME="j" CONTENT="JTable" CHAPTER="Swing Docs"></CRITERIA>
         </SEARCH>
    </HELP>

Mail Meto leave your thoughts/suggestions on this tool.
I started this just to learn XML and parsing XML using dom4j.
So This tool may not be fool proof .Positive suggestions and guidelines can help make it one