chm

You have probably seen it as part of many software applications. The compiled file will have the extension "CHM" and when run, it will look something like this little example, which compiles a simple web site:

What do I need to make CHM files?

You can make CHM help files from a set of HTML files. You can create these easily with WikiWriter (see issue #105) or another HTML editor, or even with Notepad. You can use an HTML editor written in Liberty BASIC, like the one by David Drake at The Liberated Code Foundry,

If you use an HTML editor such as WikiWriter, follow the guidelines that come with the application. For a brief tutorial that explains simple HTML creation in a texteditor such as Notepad, see issue #52.

How do I write good documentation?

See issue #105 for "Help (...is on the way)" by Jerry Muelver.

How do I compile HTML pages to a CHM file?

You use the free Microsoft HTML Help Workshop available for download here:

HTML Help Workshop Page

I've got HTML Help Workshop and HTML files... now what do I do?

Here is a step-by-step walk through that creates a compiled help file from a set of HTML files. The project shown here is included in the zip archive that accompanies this newsletter. It includes HTML, HJP, HHC and HHK files.

Create a new project in HTML Help Workshop by choosing "File", then "New", then "Project."
Select a folder for the project - choose the folder that contains the HTML files. Click the "Browse" button to select a folder and type a name for your project.
The wizard gives you the option to choose existing files when creating the project. Select "HTML files (.htm)" option by putting a mark in the checkbox.
Click the "Add" button to find your directory and select all of the HTML/HTM files.
The wizard finishes and your project will look something like this:
Click the top "Change project options" button and use the "Options" dialog to specify the default topic from your list of HTML files. You should also give your project a Title in this dialog. The Title will be displayed in the titlebar of your finished project.
You have now done enough to compile a CHM file. At this point, it will not have the space on the left side with Contents, Index and Search features. Your project will be much more user-friendly if you add these navigational aids, and it only takes a little more work. You have been working in the "Projects" area, and to get back to it any time, click the "Projects" tab. In all of the areas, Project, Contents, and Index, you will find buttons along the left side that allow you to add and modify items and settings for that area.
Table of Contents: Click the "Contents" tab in the main workshop window to create a Table of Contents. Choose to "Create New" file. Click the "Add" button to add a topic to the TOC. You'll be asked to name the topic and click the "Add" button to choose the html page for the topic. This example calls the topic "Main Page" and specifies "index.htm" as the HTML page for the topic.
Click the "Insert Page" button to add more topics, each time giving the topic a name and an associated HTML page as you did in the previous step.
Index: Now you can add keywords to your project, so that your users can find things easily in the navigational index. Click the "Index" tab, then click the "Insert a keyword" button to open the keyword dialog.
Type a keyword or phrase, then click the "Add" button to select the HTML file(s) to associate with it. This information will be used to create an index.
Search: If you want your users to be able to search the file for any term, then you must be in the "Project" tab in the workshop window and click the top button on the left side to "Change project options." You will invoke the options dialog. Click the "Compile" tab and check the box that allows full-text search information to be included.
Now you are ready to create the compiled help file. Just click the "Compile" button or choose "Compile" from the "File" menu and you are finished.
Your compiled project will look something like this:
Users can find keywords in the index, or even search the file.

To run a CHM file from a Liberty BASIC program, use the ShellExecuteA API call.

'this runs the sample file
'mainpage.chm

    lpszOp$ =  "open"
    lpszFile$ = DefaultDir$+"\mainpage.chm"
    lpszDir$ = DefaultDir$ 
    lpszParams$=""

    CallDLL #shell32, "ShellExecuteA",_
    hWnd As long,_      'window handle or 0
    lpszOp$ As ptr,_    'operation to perform
    lpszFile$ As ptr,_  'file to run
    lpszParams$ As ptr,_'any parameters needed
    lpszDir$ As ptr,_   'default directory
    _SW_SHOWNA As long,_'show window parameter
    result As long      'success result > 32

if result > 32 then
    print "Success."
else
    print "Error."
end if

end

More Ideas!

You can do a lot more with HTML Help Workshop than we have discussed here. Why not investigate the possibilities, then submit a follow-up article on "Advanced HTML Help Workshop Use?"

LB Clipboard Commands