HelpFileBuilder for RamHelp

A Great aid to creating RamHelp XML files is the HelpFileBuilder. It is a sleek Java/Swing based tool that has a self explanatory user interface. It consists of four main sections.

(Note : Please go through the help file on using the RamHelp XML Structure)

1. The Header Info Section

2. The Contents Section

3. The Search Info Section

4. The Comments Section

5. The HelpFileBuilder Toolbar

The Header Info Section

This section takes the information about the Help file and has four fields:

a. Author Name – The name of the person creating the help.

b. Help Title – The title for the help.

c. Help Version – The version of the Help and

d. Creation date – The date when the help file is first created/updated.

Of the four, the fields for Author Name and Help Title are mandatory.

The other two, namely the Creation Date and Version are not required. When the version is left empty, an entry 'U' will be made in the XML file and for a non entered date, the current date will be entered.

On entering all the data in the first section, we would have filled the <INFO> tag with all the mandatory information.

The Contents Section

This section is where the Help Contents are entered.

The basic idea is to have contents under chapters. For example, There may be a chapter Introduction under which we may have sub chapters (contents). An example.

If the Help title is Java, then we can organize the introductory chapter as follows.

• Java

  1. Introduction to Java

     • The Green Project

     • The creators

     • The Features of Java

     • The advantages of Java

  2. Data types in Java

     • Blah

     • Blah

     • Blah

This is the way in which RamHelp organizes its contents. (This can be found in the RamHelp XML documentation also).

The contents section is a pretty elaborate section with some handy features.

There are fields for The Content Title, The path for the corresponding HTML file, and the chapter under which the content appears.

So in our example, The Green Project will be a content Title, under the chapter Introduction to Java and will have a path that points to some info on the Green Project.

From the above screenshot, it may be seen that there are two browse buttons that are present along side the content path and the chapter name fields. The first one is to select a local HTML file. The browse button present along with the chapters field launches a list that includes all the chapters that have been entered for that help. If there are no chapters, a warning message is given.

There is a table on the right of the screen, that will contain the content information that has been entered. The first column named MARK can contain two values (YES/NO). This column is used to select rows that are to be removed. A drop down editor gives the user the option to select either YES/NO. When the remove button is pressed, all the rows that read YES will be removed. (Bug) To select all the rows in one click, the user must click on the header (MARK) itself. That will set the values for all the rows as YES. The user can toggle between YES and NO this way.

The Search Info Section

This section is similar to the contents section. This section is optional and can be omitted if no search feature is required. Some default search functionality based on string matching will be provided by default. However, for keyword based search, search info has to be entered.

To enter a search information, a keyword needs to be selected. This is enterd in the search Key field. This is followed by the content name where the keyword can be located. Then the chapter in which the content for our search can be located is entered. This is because in RamHelp, there is no direct display of the help page based on a keyword. There is an output dialog that displays the search results.(Bug)

Tip : Always use the content and chapter browser to choose contents and chapters for building help files quickly and also to avoid possible spelling errors.

The Contents and the Chapters dialogs :

The Comments Section

Comments are a very nice way to tell other people who work on anything that you have developed. Comments ,may be anything from a history of changes that have been made to the help documentation that has been created to the information on what needs to be done. However, it has been made optional. The comments tab is the last tab of the HelpFileBuilder.

The HelpFileBuilder toolbar

Right below the tabbed pane of the HelpFileBuilder, lie an array of buttons. The significance of each of these buttons is as follows.

The Previous Button - helps you to go one section behind at a time.

The Next Button - helps you to go one section ahead at a time.

The Open Button - helps you to load the tool with an already created HelpXML file.

The Build HelpXML Button - Builds the Help XML file from the data provided.

The Preview Help Button - Lets you preview the created or loaded XML file as a help window.

The Exit Button - Closes the Application.

The Help Button Launches the Help for this application (Built using the HelpFileBuilder !!!)

The About Button Launches a dialog to show the product information.

Planned Enhancements

For the future, I am planning to incorporate direct help launching from search results, fix a few bugs that are nagging the otherwise nice tool.

Contact me @ rsramanujam@rediffmail.com for all your comments, suggestions and bug reports.