GWBHTMLHelp Template for Clarion

This document, and associated files referred to within, constitutes the full documentation for GWBHTMLHelpä template for Clarion for Windows. This template is 100% source code, no DLLs, no black boxes, no copy protection, no evaluation version. Therefore if you are considering purchasing the GWBHTMLHelp template you must use this document as the basis for that purchase decision.

GWBHTMLHelpä - Creating Help Systems for Clarion

Clarion for Windows uses templates to create most of the procedures in an application and it therefore makes sense that a template should also generate a help system for your application. GWBHTMLHelp is a template designed specifically to build HTML help for you applications, quickly, easily and reliably. This template evolved from the original GWBDoc template set developed in 1998. Since then help systems have moved on and HTML help is now the standard and is a far more flexible and powerful help system than the original Windows help and GWBHTMLHelp takes advantage of this power!

What is HTML help?

HTML files

The beauty of HTML help is that it is based on simple HTML, or web, pages. Technically a website can be used as the basis of HTML help. So the first step in creating HTML help is to create the web pages and links as the means of documenting your application.

The biggest benefit of this technology is that you are freed of proprietary programs for creating the help system and your help system can be displayed on websites running any web browser.

Another advantage is that maintenance of the help system can be extended to your end users! If they want to add, or amend, your help system all they need to do is edit the HTML files!

CHM files

Desktop applications currently have additional needs beyond what can be provided in simple HTML help files.

Context Sensitive Help

Firstly, there is context sensitive help. When using desktop applications users expect to be able to press the F1 key and have an explanation of the page they are currently using.

Keyword search

Probably more important is key word searching capabilities. If the user can’t find what they want on the default help page that appears when they press the F1 key, they certainly want to be able to find more information by searching for “key words”.

CHM for Desktop apps

This is where the concept of CHM files for desktop applications originates. A CHM file is a series of web pages that have been compiled with Microsoft’s HTML Help Compiler. Also compiled into the CHM file are the associated files – images, Flash, layout, fonts etc - that constituted the original web design, and the resulting CHM file is compressed in the process!

To help navigation, the CHM compiling process needs at least three additional files, namely Project, Contents and Key Word Index to be available. These are also HTML files, but they have a specified structure and take the suffixes of “HHP”, “HHC” and “HHK”.

How can I create HTML help?

Are there any specific tools available?

Since HTML help is based on web pages and the Microsoft HTML help compiler there are only two types of tools required – something to create the HTML pages, and the compiler.

HTML Editors

Take your pick of HTML design tool. Some WYSIWYG editors, like Microsoft Word, are simple to use and allow the design of quite complex, and attractive, layouts. However they can add a lot of baggage, in terms of unnecessary code. This is important if your help system is going to be used over a slow web connection, but is less important for a desktop help system. (I created the HTML version of this document by using the “Export to Compact HTML” option from MS Word 6.0)

At the other extreme are simple text editors. These create bare-bones web code but require a fair bit of experience and some trial and error (even for experienced users) to create attractive layouts! In my experience, the more experienced you become in writing web code the more you tend towards simple text editors. However, the production of effective help systems is 50% design, so don’t get too hung up on writing or needing efficient code!

Microsoft HTML Help Workshop

The Microsoft Help Compiler is a free product from Microsoft, and part of an excellent free tutorial called “Microsoft HTML Help Workshop” which can be downloaded from this link.

You will need to download and install this application if you intend to create CHM files. If you intend to learn how HTML help works, it is worthwhile working through the tutorials. A book, with the same title, is also available for purchase, but is out of print and might be hard to obtain. The ISBN is 1-57231-603-9 this link might help you find it. The book is more detailed than the online documentation and worth getting, if you are keen!

NOTE: This is the only HTML help compiler there is, all tools that generate HTML help use this compiler!

HTML help designers

When you use GWBHTMLHelp to generate your help system, these programs are optional. The main reason for purchasing one of these tools is to gain a WYSIWYG HTML editor, screen capture, visually oriented help system editor, and in some of them a CHM to PDF or DOC converter is also included. If you already have these components available separately then you don’t need one of these.

There are plenty of HTML help design programs available. Some are shareware and inexpensive, others are more expensive. Take your pick.

Help and Manual

Many Clarion users like “Help and Manual” which is $US499.00. Help and Manual is a very powerful product, for the price, but suffers from not being able to import the standard files used by the Windows HTML compiler. Namely, HHP, HHC and HHK files. It is possible to import from a compiled CHM file, so you’ll need to compile your help system created with GWBHTMLHelp before you can edit it with Help and Manual.
I could not import some files created by DrExplain, and the formatting of imported HTM files was not what it should be.
Experienced users of Help and Manual might be able to overcome these obstacles, but you have been warned!

Helptron

I purchased Helptron a while ago because I liked the layout of its designer and I find it does everything I need, including source editing, export to DOC and PDF. It costs 179.00EUR and works flawlessly with the output from GWBHTMLHelp.

Windows Help Designer - HTML

Although I hate the “generic” name of this product, “Windows Help Designer – HTML” from Visage Software looks like a reasonable tool for only $99.00. However the online help is incomplete and I couldn’t figure out how to generate a manual from the help file, which it is supposed to be able to do. Otherwise, it is a very simple, and user-friendly program for WYSIWYG and source editing of the components in HTML help. It imported all the standard HTML Help files from GWBHTMLHelp flawlessly.

Help Scribble

Similarly, I downloaded HelpScribble, a popular shareware help authoring tool, but it doesn’t support the import of standard HTML help files, so you can ONLY use HelpScribble to create your help, and in my terms it is therefore useless!

Conclusion

It might be a case of getting what you pay for, so if you feel that you need to buy a program, please look carefully. In my opinion, don’t purchase one of these programs until you feel that you really need one. If you want to convert your CHM file to a PDF or DOC files, then the more expensive tools will do this, but there are also $20.00 tools that do the same thing.

Dr Explain

DrExplain, a new product in this market, presents a slightly different concept. DrExplain has a sophisticated screen capture and documenting tool, and also generates HTML help. In my opinion DrExplain would make a useful addition to the GWBHTMLHelp template because of its ability to easily create visual documentation for a procedure.

However, at this stage DrExplain does not import HHP or HTML files, so it is a product most useful for its screen capture capabilities, or for complete creation of HTML help without the GWBHTMLHelp template. At only $79.00 it is definitely worth considering.

Macromedia Flash files

Macromedia Flash files are becoming the de facto standard video format for web sites. Since Flash files can be displayed on HTM pages they can also be used in HTML help. There are numerous tools available for creating Flash tutorial documentation, priced from free to hundreds of dollars.

Wink

Wink is the only product I’ll recommend here because it is free, and does everything I need a tutorial creation program to do, simply and efficiently. The only thing lacking from Wink, which is found in its more expensive competitors and, in my opinion worthwhile, is the ability to add sound to the tutorial. If you’ve heard my voice, you’ll know that most people will regard this omission as a benefit!

What do the Clarion Help Templates do?

Clarion 6.x includes an HTML Help template, what does it do? The magic of context sensitive help available in the use of a CHM file for a help system is called using help system APIs. The Clarion HTML help template includes those APIs and makes the appropriate call whenever the user presses the F1 key, or clicks on the “Help” button placed on procedure windows.

This functionality was only added in Clarion 6, but similar functionality can be added to previous versions of Clarion either manually, or by using a free template available for download from Solace Software.

Where Does GWBHTMLHelp fit in?

The biggest problem with creating help systems for your Clarion applications can’t be addressed by any of the tools discussed above!

The fact is that your Clarion applications are complex – otherwise you wouldn’t need to write help systems, right?

When designing help you need to

Create a help system which users can navigate logically,
Remember to cover most of the procedures in your application,
Know what most of those procedures are called,
Remember the help ID you created in the procedure that links it to the help system,
Create links to your Key Words on every page those key words might appear on,
Write the actual help text, or advise your text author what the help window is meant to explain,
Make it attractive!

GWBHTMLHelp does all this for you, except for writing the help text, in seconds!

Help file structure

The menu structure of a help system is remarkably similar to the procedure view structure found in your Clarion IDE. If you have created your application logically, then using the same structure for your help system contents makes perfect sense!

This is the basis used by the GWBHTMLHelp template to generate your help system. It takes your procedure tree and converts it to an HTML help contents page. So navigation within your help system is analogous to navigation within your application. If a browse procedure calls an update form, you browse help will link to help for the update form.

This is the hardest structure to get right in a help system, and with GWBHTMLHelp template, it can’t get any easier!

Procedure level help

For each procedure in your help GWBHTMLHelp will create a separate HTML page. From within your application you specify the title, subtitle, and help text that appears on each page. These come from the Description and “Long Description” that you enter into each procedure. If you do this as you create your application, the help system is written for you as you go. By using this built-in text your help system is safe within the application, no chance of it being lost or forgotten.

The page title for each HTML page created is saved in a new field added by the GWBHTMLHelp template.

The GWBHTMLHelp template sets the help ID for every procedure, so there is no chance that you will forget to assign an ID. You can disable help creation for any procedure; for example, source code procedures probably won’t need help.

Field level help

Creating context sensitive help for an individual field is just as simple. Specify a help ID for a window control and the GWBHTMLHelp template will look in your dictionary and use the Description and Long Description that applies to the fields USE variable and create a help page from that. If you haven’t set a description in your dictionary the template simply creates a blank page you can edit later.

Key Word pop-up help

Does your application require the use of jargon, or key words that some users might be unfamiliar with? If so, create a list of these key words within your application and GWBHTMLHelp will create a pop-up hyperlink explaining these words on every page that the word appears on. A glossary is also created listing every key word that you have specified.

Introductory pages

If you want to make your help system look even more professional you can specify introductory pages within the GWBHTMLHelp templates. As many as you need!

Which versions of Clarion?

The GWBHTMLHelp template works with Clarion and ABC template sets for versions of Clarion 5.0, 5.5 and 6.x.

Context sensitive help functionality is not supplied with these templates. Third party templates are required for this and are supplied by Softvelocity with Clarion 6.x, and otherwise as mentioned.

How do I use GWBHTMLHelp?

Installation

The GWBHTMLHelp template is 100% template code – no black boxes, no DLLs, no time or use crippled applications. Installation is simple, and transparent. There are no changes to your system.

1. Unzip the supplied zip file.

2. Copy all the files to your Clarion /Templates/ folder, or some other convenient folder.

3. Open Clarion.

4. Select Setup/template registry from the main menu.

5. When the registry opens select Register and select “gwbhtmlhelp.tpl”.

6. Close the template registry.

The Global Template

Open an application and select “Global Properties” then “Extensions”.
Click the Insert button and choose the Clarion template called cwHHGlobal. Specify a default file name ending in “CHM”. Tick all the checkboxes, and nominate an alternate key code to call the help, if necessary only.
Click insert again, this time choose the GWBHtm_HelpWizardSetup template.

Help IDs tab

This tab is self-explanatory. Nominate a “Main Html file” is an important step. Be sure to create a separate folder for this file. All files generated by and used by the GWBHTMLHelp template will be placed in the same folder as this file. ApplicationName.Htm is a safe choice for this file, be careful not to name this file ProcedureName.Htm, or the files created by the template will overwrite it.

External Files Tab

A great feature of the GWBHTMLHelp template, compared with the previous version, is that you are no longer limited in the size of the help that you create for each procedure. HTML help is standard format code and it is therefore possible to import code from external HTML files into your help system. GWBHTMLHelp does it automatically! All you have to do is name the external file ProcedureName_X.htm or ProcedureName_X.html, and place it into the same folder where GWBHTMLHelp generates your help system.

When GWBHTMLHelp generates your help system it will look for appropriately named files and either import them into the your ProcedureName.htm, or create a link to the external files. You choose which action is taken on this tab.

You can also import external ProcedureName_X.txt files into your ProcedureName.htm file.

In all cases, “X” represents a number from 1 to 10, so in total, up to 30 external files can be imported into every ProcedureName.htm file!

Glossary and Introductory Pages Tab

This tab is where you specify Glossary, or Key Words, and Introductory pages for your application.

Edit Glossary Keywords

Click this button to add Key Words to your help system.

You’ll see a list of currently defined key words; click Insert to add some more. All these key words get added to a “Glossary” within your help system. As GWBHTMLHelp generates your help system, it searches through the help text you’ve have written, and also through any files that get imported into your help for these keywords. The first instance of any of these keywords that appear on each help page will be made a hyperlink to a pop-up window showing the Explanation you have specified!

This process only hyperlinks the full key word, note in the above example that information is not hyperlinked. Clicking a keyword hyperlink pops-up the appropriate help…

Adding this functionality manually to a help system could take you hours! GWBHTMLHelp does it for you, automatically.

Edit an Introductory Page

It is common for help systems to have several introductory pages. You might use these for licensing statements, welcome windows, getting started, and etcetera. These are added to your GWBHTMLHelp system by pressing this button.

These pages can have multiple paragraphs, insert as many as you need. The HTM files generated for these pages are named from the Title you specified for the page, with spaces removed. So the page shown in the above image will be named “WhoshouldUse.htm”

Procedure Template

The procedure level template is added to every procedure automatically when you register the global GWBHtm_HelpWizardSetup template. GWBHTMLHelp does not interfere in any way with your procedure Descriptions or Long Descriptions, which remain with your application whether this template is present, or not.

This template is access by opening the procedure properties window, and clicking on the “Extensions” button. You have the option of disabling generation of a help window. You also can specify the Title appearing at the top of the help page.

In this example, “Class Tree Procedure” is the nominated Title. “The Class Tree Procedure” subtitle came from the Procedure Description field, and the help text came from the Procedure Long Description. If I left the Title field blank the title would be the Procedure Name.

The list of “See Also…” procedures came from your application design window. Since these procedures are linked to the “ClassTree” procedure, GWBHTMLHelp automatically creates the links to the relevant help windows. You designed your help as you designed your application – you’ve saved yourself days of work already!

The “HelpID: ClassTree” notation at the bottom of the window came from the global GWBHtm_HelpWizardSetup template, on the “HelpIDs” tab.

The style of the window is specified in a Cascading Style Sheet named “GWB.CSS”. This file is optionally generated from default styles specified in the utility template. You can change the styles in the GWB.CSS file, or override the styles in a “Styles.CSS” file that is also linked into your help system.

Utility Template

The utility template “GWB_HtmHelpWizard – Create Help Systems” is what generates your help system. It will only work if you have already added the Global template to your application. You access the utility template by selecting Application/Template Utility from the Clarion menu while your app is opened.

Then select “GWB_HtmHelpWizard – Create Help Systems” from the list.

On the second tab you have two options, “Generate Default CSS file Now?” and “Generate HTM Files Now?”

The first time you generate your help files you need to check the first checkbox. After that this is optional. If you make changes to GWB.CSS you want to be sure to NOT check this checkbox, because the template WILL overwrite your changes.

The second checkbox will most times be checked. This is what triggers your HTM file generation.

Running this template utility generates a file named “_ApplicationName_help.txt” containing a summary of the help settings used when your help system is generated. The naming is designed to bring it to the top of your file view in Windows Explorer, so you can find it easily.

Your Help System Files

After running the template utility your nominated folder will contain the following files…

HelpName.htm – the default HTM file you nominated for your help system.
ProcedureName.htm – a window for every procedure where the template is not disabled.
IntroductoryPages.htm – a window for every introductory page you created. These files are named from the Title you specified for the page, with spaces removed.
If you specified Glossary Key Words…

“Glossary.htm” a web page summarizing your glossary.
“Glossary.js” a JavaScript formatted file containing the pop-up text for your glossary key words.

“Contents.HHC” your help system contents file.
“Index.HHK” your help system index file.
HelpName.HHP – the project file for your help system.

The final three files are only needed if you intend to generate a CHM file.

Creating the CHM file

Creating the CHM file is very straightforward. After installing the Windows HTML Help Compiler, all you need to do is double-click on the HelpName.HHP file from within Windows Explorer. This will load HTML Help Workshop and your help files.

Now click on the meat-grinder icon, select the file you want to compile, and wait. In a couple of seconds you will see a compile summary window.

Your CHM file is now ready to be used. Copy it to the same folder as your application EXE file.

What else can I do with GWBHTMLHelp?

Using embedded HTML tags

Whatever you type into the Description and Long Description fields in your procedures only needs to be plain text. Carriage returns are converted to new paragraphs by the GWBHTMLHelp templates, so your text is automatically formatted for you without the need to remember obscure codes. As mentioned above, you can embed HTML code by getting the template to import HTM files created externally to your application.

You can also embed standard HTML tags within the Long Description fields in your application. So if you are familiar with HTML, you can easily add “strong”, “italic”, bullets, or whatever, to your embedded code to achieve any desired formatting supported by HTML. This extends to the use of CSS class tags, if you wish, by adding the tags to gwb.css, or styles.css.

In the following example, from the Update Courses procedure, I have added formatting to a few key words. Whether you choose to embed HTML code within your application, or rely on importing HTML code created externally is entirely up to you, both techniques are supported by GWBHTMLHelp.

Using DrExplain files

DrExplain is a great tool to create documentation files for your procedure windows. These HTM files can be imported into your GWBHTMLHelp very easily. All you need to do is export the files from DrExplain to HTM. Then rename these HTM files to match the file names used by GWBHTMLHelp and copy all the DrExplain files to your GWBHTMLHelp application folder.

For example: I have a procedure called “UpdateStudents” that has three tabs. In DrExplain I create three separate documentation windows – one for each tab in my procedure. I export these windows to HTM – DrExplain exports the HTM files and all the associated images from my documented windows. DrExplain names the HTM files window_1_1.htm, window_1_2.htm and window_1_3.htm. To import these into my GWBHTMLHelp I rename them to UpdateStudents_1.htm, UpdateStudents_2.htm and UpdateStudents_3.htm respectively and then copy everything to my folder where the GWBHTMLHelp files are. The next time I run my utility template these files are imported into my UpdateStudents.htm file and I now have all three tabs documented on the one screen. If I wanted to keep the DrExplain windows separate I can choose to LINK external files, instead of IMPORT, in the global GWBHTMLHelp template settings. Linking the files will cause the utility template to create a separate link to each external HTM file.

Using Macromedia Flash help windows

It doesn’t take long to become a convert to using Flash video tutorials in help systems! I’m about to spend half an hour creating a WINK Flash tutorial for the GWBHTMLHelp templates. The resulting video will explain better, and be viewed more often, than this Word document – which has taken me about 10 hours to create! Using Flash video tutorials is a win-win situation for developers and end-users.

Adding Flash video to your GWBHTMLHelp systems is a piece of cake. For each procedure where you create a WINK Flash video simply name the generated file ProcedureName_1.htm and copy it, and the associated Flash file, to your GWBHTMLHelp folder. The utility template will import the HTM file, plus it will add the associated Flash file to your help system project.

If you use WINK to create the video the HTM and SWF files created will both be named ProcedureName_1, so you simply copy these two files to your folder.

When the Windows HTML Help Compiler compiles your help system the Flash files will be included in the CHM file, you won’t need to distribute them separately.

Multi DLL apps

The easiest means of handling HTML help in multi-dll apps is to create a “dummy” parent application that includes all the procedures from your DLLs. You can do this by importing the procedures from the child apps; either by using the standard Clarion “Import Text”, or “Import from Application” options.

This parent application will allow your help contents page to be created with all the correct links and structure for all the procedures in your application. Within each DLL you then need to specify that the help file for use with this DLL is the same help file that you nominated in the parent DLL. This is the CHM file that you name in the Clarion HTML help global template, which specifies the appropriate context sensitive links.

Licensing and Cost

Purchase Price

The purchase price for the GWBHTMLHelp templates is $US79.00. The template is supplied by file download only, from the Comformark Pty Ltd website.

License and Copyright

GWBHTMLHelpä template is the original work of Comformark Pty Ltd. Comformark Pty Ltd retains copyright and all other rights to the templates and source code, worldwide.

Purchase of the GWBHTML Template grants the purchaser permission to use the template within their business on any one machine at any one point in time. If two employees wish to use the template concurrently then you should buy two licenses. The template may be used by outside contractors, so long as it is not being used concurrently without a separate license.

The GWBHTMLHelp template may only be supplied by Comformark Pty Ltd. Any other supply of the GWBHTMLHelp template to any third party is theft.

Upgrade Policy

The purchase of a license for GWBHTMLHelp will grant the purchaser rights to future upgrades of the template at no charge, if and when they become available. Free upgrades are limited to GWBHTMLHelp with respect to its use for creation of HTML help using the Windows HTML help compiler. No promises or obligations with respect to future versions of help system development (HTML or otherwise) are stated or implied.

No claims are made with respect to the suitability of GWBHTMLHelp for use with any future version of Clarion.

Warranty

This document, and associated files, explains the intended use of the template, and the expected outcome from using the template.

If you have read this document and found that the template does not meet your expected needs, please contact the author before purchasing GWBHTMLHelp. No refunds will be supplied if you subsequently find template does not supply functionality not mentioned in these documents.

Liability

Use of GWBHTMLHelp is entirely at the risk of the purchaser.

Comformark Pty Ltd will not compensate for any loss or damage to applications, to end users, to third parties, or anyone else, or anything else, caused directly or indirectly through the use of GWBHTMLHelp.

Disclaimer

All opinions are the opinions of the author only, and are based on the limited experience of the author with the third party tools mentioned. More experienced users of these tools will probably have different opinions.

Prices quoted in this document were accurate as of November 27, 2005.