NOTE: This Technical Note has been
retired. Please see the Technical Notes
page for current documentation.|
Using Guide Maker for Conversion
The only publicly-available tool for converting WinHelp to Apple Guide is Guide Maker, Apple's official development environment for creating guide files. You can find it in the Apple Guide section of the Mac OS SDK. Guide Maker converts the WinHelp source RTF files to Guide Script source RTF. There is some preparation required, however, for this to be successful.
Preparing the WinHelp Source RTF Files
The Guide Maker converter requires the WinHelp source files to be RTF (Rich Text Format) but does not use the XTND for translation (unlike the Guide Maker compiler which does use XTND for RTF and other formats). The converter reads the raw RTF directly and does a pattern match search for various items. This is one of the key problems with the converter because you can have several different variations of raw RTF text that mean the same thing. Unfortunately, the converter can only understand a few of these variations. The "safest" variation is the RTF exported by Microsoft Word 4, which is what all of the test cases were taken from when the converter was written.
If the WinHelp source files are in RTF created by Word 6, there may be problems. Several RTF tags exported by Word 6 aren't understood and cause Guide Maker to crash. If you encounter this problem, convert the Word 6 RTF to an earlier RTF version. This can be done as follows:
You can also use Word 4 instead of Word 5.1.
On a Power Macintosh, you need to install the XTND Power Enabler in your Extensions folder. This is required by Guide Maker whether or not you are using any XTND translators. The XTND Power Enabler extension is available on the MAC OS SDK in the Guide Maker folder.
Be sure the WinHelp RTF source file type is 'TEXT'. This allows Guide Maker to open the file for conversion.
Also, refer to some other little "gotchas" on pages 8-3 to 8-4 of Apple Guide: Complete.
Using the Guide Maker Converted Output
The Guide Maker converter outputs its files in RTF. The first thing you should do is convert the RTF to the native format of your favorite word processor or text editor. We do not recommend that you leave the output in RTF.
To convert the Guide Maker output from RTF, you'll need a word processor that understands RTF or a word processor that uses XTND translation for RTF.
Microsoft Word is one example of a word processor that can read the Guide Maker RTF output directly. You can then save the file as "normal" Word format or as "text".
If you elect to use a word processor that requires XTND for translation, then you will need to install XTND and a RTF translator.
Two RTF translators are currently available: one from Claris and one from DATAVIZ. If you have any Claris products installed, then you already have the Claris RTF translator. To be sure, check your Claris folder in your system folder for a file named RTF. That's the file you need.
If you want to use the DATAVIZ translator, be sure to remove the Claris RTF translator from the system folder. The RTF translator from DATAVIZ comes free with the retail version of System 7.5. It is not included on the floppy version, just the CD-ROM version. This translator is installed separately from your system software installation. Users have reported that the DATAVIZ RTF translator is more robust than the Claris version.
Before you save the converted file, be sure it ends with one or more 'return' characters. To be safe, go to the end of each file and enter a few return keys. Save the file in your favorite format or as "text".
Determining If the Translation Was Successful
To determine if your translation is successful, examine the Guide Script output after you have converted it from RTF. You can use a word processor or text editor for examining and editing the files.
If the conversion occurs properly, the resulting files will contain, for example, the following Apple Guide script commands:
<Define Sequence> "Decompressor_Functions"
To find the Guide Script commands, you need to search for the < character.
Steps to Fix the Converted File
Guide Maker does not perform the conversion, however, without a few errors. In the previous example, you need to fix the following the RTF conversion errors by hand:
The DATAVIZ RTF converter errors and fixes:
Error: <Define Panel> 5Panel 34"
The necessary fix: <Define Panel> "Panel 34"
Claris RTF converter errors and fixes:
Error: <Define Panel> Panel 34"
The necessary fix: <Define Panel> "Panel 34"
The string following the <Define Panel> is the name of the panel and must be unique. You may need to invent new panel names when you make the fix.
Running the WinHelp files through the Guide Maker converter is only the first step to making a good Apple Guide file.
Refer to the StepUp Software web site <http://rampages.onramp.net/~stepup/> for the latest information on WinHelp conversion and a description of the complete conversion process.
Porting WinHelp source files to Apple Guide is, by and large, a straightforward conversion process. However, there are some important steps you need to follow which aren't completely documented. This Technote tells you what you need to do in order to perform successful conversions.
The following references provide you with additional information on Apple Guide and the WinHelp conversion process.
Apple Guide Complete by Apple Computer, Inc.
The Apple Guide Internet mailing list . Send a message to: firstname.lastname@example.org with the text "subscribe apple-guide Your Real Name" in the body.
StepUp Software Web Site. See the web site for the latest information on Apple Guide including WinHelp conversion - <http://rampages.onramp.net/~stepup/>
Apple's Apple Guide Web page <http://www.macos.apple.com/Apple_Guide/>
Contact ADC | ADC Site Map | ADC Advanced Search
|For information about Apple Products, please visit Apple.com.|
Contact Apple | Privacy Notice
Copyright © 2002 Apple Computer, Inc. All rights reserved.