HCMAC Macintosh Help Compiler and Converter
COPYRIGHT (C) 1997,1998 Stephen Sweet


INTRODUCTION

HCMac works as three programs in one:

1) a 32 bit Windows95 application that converts existing .HLP Windows help files so they can be viewed with the Macintosh Help Viewer from Microsoft.

2) a Windows95 Help Compiler front end that allows the user to maintain and compile a single .HPJ help project file to generate both Windows and Mac versions of the help file.

3) an extension to the Microsoft Visual C++ Cross Development edition so that help files can be automatically updated on the Macintosh target platform after compilation.


SYSTEM REQUIREMENTS

For Conversion Only:
1) Windows 95

For Conversion and Compilation:
1) Windows 95
2) HCRTF.EXE Microsoft Windows Help Compiler

For Cross Development Automatic Target Update:
1) Windows 95
2) HCRTF.EXE Microsoft Windows Help Compiler
3) MFILE.EXE Microsoft Cross Development Copy Utility and associated Macintosh files.
4) Serial or TCP/IP network between Windows and Mac


WHY YOU NEED HCMAC

The problem until now has been that in order to create a Macintosh help file, you needed to use HC35.EXE, or go to an expensive outside vendor and pay large royalties and license fees. HC35 works very poorly, with the user having to break up the files into very small sections, and running out of memory with bitmaps of any decent size. Also, images were scaled incorrecly, and so screenshots of dialog boxes, controls and windows looked lousy. HCMac overcomes these problems and more.

Here's how it works: HCMAC uses your normal Windows .HPJ help project file, and first runs HCRTF.EXE, the windows help compiler, on it. Your windows help file is created in the normal way in the normal place. HCMAC then makes a copy of this file with a .MAC extension and begins doing it's dirty work on it. After the file has been fixed, it is copied to the Mac with the MFILE copy utility.


INSTALLATION

Macintosh Platform
Using RESEDIT, increase the 'SIZE' resource of the Microsoft Help viewer. The best setting I have found is 1441972 and 393216.

Windows Platform
Create a new directory of your choice on the Windows machine. e.g. C:\HCMAC

Copy the file HCMAC.EXE into the new directory.

Create a shortcut to HCMac.exe

Run HCMac and choose the SETTINGS menu.

Enter the path to your copy of the HCRTF.EXE Windows95 Help Compiler.

(Cross Development Edition users only)
Enter the path to your copy of MFILE.EXE

Enter the default Macintosh path you would like MFILE to copy the results to. An example of the Macintosh path
is :Macintosh HD:My Project:Help


INSTRUCTIONS ON USE

1) Conversion of existing .HLP files

Select the FILE/OPEN command from the menu.

Select the FILE/CONVERT command from the menu.

The output will be a file with a .MAC extension in the same directory as your .HLP file.

Copy the output file to the Mac either with your network or on a floppy.

Using RESEDIT or another disk utility, change the file creator to 'MSH2' and the file type to 'HELP'.


2) Compilation of .HPJ files

(Cross Development Edition users only)
If you want to have HCMAC copy the results to the Mac, add a line to your .hpj file in the [WINDOWS] section as follows:
Macintosh=":Mac HD:MyFolder:MyHelpFileName"
The path follows the conventions of MFILE. This will cause the help compiler to kick out some warnings which can be ignored.

If you don't use this option, the default Macintosh path from the SETTINGS menu will be used.


(All users)

Open an .hpj file with the FILE/OPEN menu.

Compile using the FILE/COMPILE menu.

The main window will tell you everything that happened, and will give you any error reports from the compiler. The file will be copied to the Mac if you selected that option.

In all cases the Macintosh help file will be created using the same name as your .HLP file, but with a .MAC extension. This file may be copied to the Mac using whatever method you find easiest.

Unless you use the Cross Development Edition MFILE utility option, you will need to manually change the help file's file creator and type to 'MSH2' and 'HELP' respectively using RESEDIT or your favorite Mac disk utility.


FILE DISTRIBUTION

In addition to the help file created with HCMac, you will need to distribute the Microsoft Help viewer with its SIZE resources increased. I have found it easiest to install this into the same folder as the help files. You can of course check to see if the end user already has this program installed, but the SIZE resource must be increased for large images to be viewed.


HINTS

Increase the memory required in the size resource of the Microsoft Help viewer in order to display larger bitmaps. The best setting I have found is 1441972 and 393216.

The Microsoft Help viewer only uses one font for everything. You may need to tweak the font sizes, colors and attributes to get the effect that you want.

The Microsoft Help viewer only allows WHITE backgrounds as far as I know.

Do not use the compression option in the .HPJ file. This causes bitmaps to display incorrectly.


LIMITATIONS

The same limitations apply with respect to macros and metafiles as found in Microsoft's documentation.

I wrote this program to compile my own help files, which are limited to about 100 pages and 60 .bmp and .shg files. Some very large help files that have a huge number of bitmaps or links may not convert, but if this is the case, I would like to know, so that I can fix it accordingly. Just send me a sample file that won't compile, and I'll see what I can do.


SUPPORT

If you have comments, questions, or additions to make, contact me at:

Steve Sweet
19348 Carriger Road
Sonoma, CA 95476

sweetsteve@vom.com
http://www.vom.com/sweetsteve

ph (707) 996 5775
fax (707) 996-6971