DAS_QuickHelp v1.20 - Tinman Development

by Shawn Mason

Published 1998-04-01    Printer-friendly version

I don’t know about you, but the worst part of any project I have ever done has to be documentation (i.e. help files). It seems that help files are the catch-22 of the industry. If you don’t have a good one… your end users scream at you. When you have a good one… they don’t use it. Damned if you do…damned if you don’t. Well, any tool designed to help facilitate this most distasteful aspect of programming is more than welcome in my book.

Tinman Software Development has created such a tool, called DAS_QuickHelp. It is not a full blown help development environment like RoboHelp or other similar help creation tools, but it is useful in getting a serious jumpstart on your help files prior to using help creation tools. In the author’s own words, "DAS_QuickHelp is a very simple Utility Template which creates near commercial quality Help Files for any existing CW APP or DCT file."

What it creates is an RTF file and an HPJ file that can then be imported into your help development environment. (If you are new to help file creation, then think of the RTF file as your APP file and the HPJ file as your project file. A help development environment uses both of these to create the finished help file.) Add a few screen shots and polish your text, and viola, you have your basic help file complete with a table of contents and even a glossary shell.

Review Editor's Note

As stated above, the RTF and HPJ files which DAS_QuickHelp creates can be imported into a commercial or shareware help development environment (such as WYSI-Help, RoboHelp, ForeHelp, Hellllp and others). If you don't have any of those tools (which can cost hundreds of dollars), you can still create help files by obtaining the free Microsoft help compiler(HCP.EXE) and using it to compile/create the final help file. You can also use Microsoft Word to polish and expand your DAS_QuickHelp created RTF file, provided you save your changes in the required RTF format before compiling the file.

Installation

I downloaded my copy of DAS_QuickHelp; therefore, the installation was a one-piece executable. After entering my personal information and the security code, it allowed me to place the shortcuts into a group of my choice (I chose my CW2.0 and Clarion4 groups, which required two separate installs). Tinman Development Corporation has a version for CW20 and Clarion4, and the purchase price includes both versions. Installation went without a hitch. I used the created shortcut to pull up the help file to guide me further.

Preparing my DCT and APP

DAS_QuickHelp is not magical. It is not a genie that sits on your shoulder and waves a magic wand and presto – out comes the perfect help file. To get the most out of the product you need to do a little cleaning up. DAS_QuickHelp relies on the field names and descriptions within your application’s dictionary as well as the procedure names and their descriptions within your application. If you will spend the time to properly comment your fields, files, and procedures then not only will you have a wonderfully documented application and dictionary, but your help file will be that much closer to being finished.

QuickHelp obtains the Field Description text using the following priorities:

1st - Dictionary Field Comment Tab
2nd - Dictionary Field Description
3rd - Application MSG field
4th - Application TIP field
5th - Application prompt for control (Better display something)

With these properly defined (thinking in help files terms as you do it), you are ready to run the QuickHelp utility.

This snapshot shows a field with its description properly identifying it.

A portion of the dictionary definition of a field

The next snapshot shows the how QuickHelp uses this information to create the help file.

Dictionary description convsion by DAS_QuickHelp

The name description of the file was used instead of the file’s actual name (which is PC). The field is then described for the user utilizing the exact text entered in the description field.

Running the QuickHelp Utility

With your application loaded, go to Application, then to Template Utility. From the choices offered there, go to DAS_QuickHelp. The utility template is a wizard that gives you many, many options about how you wish to generate your help file.

A sample screen from the DAS_QuickHelp wizard

This is the first wizard screen. You have the choice to generate either a 16 bit (Win3.1) or a 32 bit (Win95 and NT) help file. You also have the option of naming it at this point.

Review Editor's Note

The type of help file you choose to generate depends on both your intended target OS (i.e., 16-bit Windows 3.1 or 32-bit Windows 95), and the type of help compiler you are using. For example, if you have the free 16-bit help compiler, be sure to choose 16-bit.

The next screen gives you the choice of creating a help HPJ (help project file) or just the RTF file. You can create the table of contents and even the shell for your glossary (what a repulsive thought). A glossary in the most practical sense would be a pop-up list allowing your end user to see a good definition of words they might not be familiar with.

Other options include whether you wish to include all files or simply choose a few. The utility template is smart enough to ignore every file and field you have marked "Do Not Populate". How do you want your topics to appear in your help file? How about the standard inline, or maybe as popups. Just set the option and it is all done for you. It even gives you the choice to have non-scrolling regions at the top of your topics to avoid confusing your users as they scroll down through the information. How many non-scrolling lines do you want? One, two, three? You can have any number you wish. This consistency throughout your help file will give it a professional look.

As the utility template works its way through your application, you can choose what type of controls it will create topics for. Do you wish to limit the number of topics to cover only list boxes, or maybe every conceivable control (yuk, that might take awhile). Do you have a really nifty logo you would like displayed in your help file? No problem. And to top off the cake and ice cream with some really good whipped cream, you choose the fonts, their sizes, the colors, and even the alignment of the various styles of text. Wow, how about some hot fudge sauce, too? If you don't get it the way you want it with one set of options, simply run the QuickHelp utility template again and again until you do get it the way you want it.

[Review Editor’s Note: Remember, though, that in most cases you won't use the file QuickHelp creates as your final help file. For example, you will normally want to add more text that describes your program in general terms, and perhaps add other topics such as frequently asked questions, troubleshooting tips and contact information. QuickHelp can't really help you with these types of topics since they can't be generated from your app or dictionary files. The difference, however, between starting a help project from scratch and starting one with QuickHelp is like night and day.]

Documentation

As you might guess, the documentation is in the form of a help file. Although it seems as if this utility is a no-brainer, you do need to have a little knowledge of how to create a help file as well as a help-authoring tool. The help file has a complete demonstration of all the wizard’s windows complete with a good explanation of each. No printed or printable documentation is shipped.

Support

Tinman Development Corporation pulls no punches when it comes to support. They give you every available option around. You can phone them, e-mail them, use their web site, or snail mail them. I sent an e-mail to them inquiring about controls. The response came the next day. The reply was both correct and quite courteous.

Overall Impression

I’m extremely pleased with the product. It not only lives up to its promise, but also gives you more than expected. It is nice to have something that can take a lot of the grunt work out of one of the most distasteful aspects of creating wonderful software. From my table to yours Tinman, hear-hear. (A toast well deserved)

Category	Product Score
Ability to do the task	Excellent
Ease of use	Excellent
Ease of Installation	Excellent
Documentation	Very Good
Technical Support	Excellent
Modifies Shipping Templates	No
Black-Box DLLs/LIBs	No

DAS_QuickHelp v1.20 retails for $179.00 US and can be purchased via any of the following methods:

• TopSpeed Accessories Program (call 800-354-5444)
• Online via BMT Micro (https://secure.falcon-net.net/BMT/order0274.html)
• Directly from Tinman Development Corp via phone or fax (phone (316) 942-6866). Faxable form and number are available at http://www2.southwind.net/~tinman

More information can be obtained at the Tinman Development web site (http://www2.southwind.net/~tinman). All products can be downloaded and installed in 'demo' mode (this basically installs the help files, etc.; the products require a password to install the registered portions). Demos are also available on the C4 final release CD-ROM, with DAS_QuickHelp located in the \THRDPTY\DASQHELP directory.

Printer-friendly version

Copyright © 1999-2008 by CoveComm Inc. All Rights Reserved. Reproduction in any form without the express written consent of CoveComm Inc., except as described in the subscription agreement, is prohibited.

Clarion Magazine ISSN 1718-9942