4.   Quickstart

This chapter provides a quick reference for using KEYpak to convert your documents.  It also gives a brief introduction to the functions and features available with KEYpak.


KEYpak may be invoked through any of the following:

       KEYpak Command Line

       KEYpak User Interface

KEYpak Command Line

To convert a document through the KEYpak command line, use the following command:

kw [-s<src-mnemonic>] -t<trg-mnemonic> [options] <src-file> <trg-file>

                        Note        Parameters in square brackets are optional.  When entering the command from the console, DO NOT type brackets of any kind.  Unless otherwise indicated, all commands must be in lower case. 

Listed below are the interpretations of each field in the KEYpak command:


kw                                           command to initiate KEYpak.


[-s<src-mnemonic>]           specifies the KEYpak mnemonic of the source document’s format.  See Appendix A for a list of supported formats and their mnemonics.


                                                This parameter is optional.  If it is not specified on the command line, KEYpak will call upon the auto-detect function to determine the format of the source document. 


-t<trg-mnemonic>               specifies the KEYpak mnemonic of the target document’s format.  See Appendix A for a list of supported formats and their mnemonics.


<src-file>                              specifies the file and path name of the document you want to convert.


<trg-file>                              specifies the file and path name of the converted document.


[options]                                                 are other optional parameters listed below. 


-l<file-spec>                         specifies name of the log file under which all log messages etc. will be stored.  If a file name is not specified here, the log messages will default to print on your terminal.


-A                                            appends log to the existing file.  This option is used with the -l<file-spec> option.


-c<file-spec>                         specifies name of the configuration file.  Default values are assumed if no configuration file names are entered, and no standard configuration file is found.  A maximum of eight configuration files may be specified on the command line.  Each configuration file name must be preceded by a -c.  (For Example: -c config1 -c config2...etc.)


-d                                             indicates to the program that you want to ignore the configurations with any errors.


-i                                             ignores the standard configuration file.


-o<file-spec>                         specifies name of the option file.


-L<file-spec>                        specifies name of the language file for generating KEYpak warning messages.


-r<file-spec>                         logs all statistics to the file name indicated here.


-p                                             prompts for the KEYpak command line parameters.


-nl                                           disables the creation of the log file. 


-nr                                          disables all statistics. 


-q                                             turns off all screen output.


-O                                           overwrites the existing target document.


-bs                                           specifies MacBinary format for the source document.


-bt                                           creates the target document in default MacBinary format.


-bf=<name string>              specifies MacBinary file type for the target document.


-bc=<name string>              specifies MacBinary file creator for the target document.

For detailed information on the above parameters, see chapter 5 “Using KEYpak Command Line”.

                 Example        Convert a sample document

Use the following command to convert the Microsoft Word (PC) document sample.mw to the Lotus AMI Pro document sample.ami.  The log will be displayed on your terminal.

kw -smw -tami sample.mw sample.ami

In the above example, mw and ami are the KEYpak mnemonics for Microsoft Word (PC) and Lotus AMI Pro, respectively.  See Appendix A for KEYpak supported formats and their mnemonics.


See chapter 5 “Using KEYpak Command Line” for detailed information on converting documents through the KEYpak command line.

KEYpak User Interface

                        Note        To use KEYpak User Interface on a WYSE-50 terminal, you must install the terminfo database description as described in the section “Post-installation Procedure” in chapter 1.

KEYpak User Interface is a simple menu-driven program for converting documents.  To invoke KEYpak User Interface at the UNIX prompt:

Type       keypak

Press      <Return>

You will be presented with the KEYpak User Interface main screen.  This screen displays six fields and four option buttons.  Enter appropriate data in the six fields and use the TRANSLATE button to convert documents. 


See chapter 6 “Using KEYpak User Interface” for detailed information on converting documents through the KEYpak User Interface.

Important KEYpak Functions/Features

While using KEYpak, please keep in mind the following functions/features available with KEYpak.  These features/functions will inform you of any errors, facilitate file transfer situations, and allow you to customize KEYpak to meet your document conversion needs. 


Source/Target Reference Files

xxsrc.doc and xxtrg.doc are the source/target reference files for each conversion format.  xx refers to the two or three character KEYpak mnemonic of the conversion format.  See Appendix A for a list of KEYpak supported formats and their mnemonics. 

The source/target reference files are installed at the time of installation, in the “library directory”.  The source/target reference files are provided in text format and can be viewed from any text editor.  Use these files to determine configurations and their range of values available for customizing conversions.  Target reference files (xxtrg.doc) also list any character set configuration files provided with the target conversion.

Log File

A log file is used to record the summary and statistics of the document conversion process.  You can access this file to determine which features did not convert, why a document did not convert, duration of conversion, any serious error messages, etc.  This file is also required by KEYpak Customer Service to analyze any conversion issues. 

To create a log file, it must be specified on the command line or in an option file.  If a log file is not specified, it will default to print on your terminal.  For detailed information on creating log files, see chapter 5 “Using KEYpak Command Line” of this guide.

Configuration Files

Configuration files are used for customizing the conversion process.  There are two types of configuration files:

Character Set Configuration Files are provided for most of the target conversions.  These files determine how to translate source characters to the target document. 

                        Note                No character set configuration file is provided for the following formats.  For these formats, KEYpak will automatically load and map the character set files (kw*.stb/kw*.ttb) as required.


       HTML Hypertext Markup Language (HTM)

       Lotus AMI Pro (AMI)

       Microsoft Rich Text Format (RTF)

       Microsoft Word for Mac (MWM)

       Microsoft Word for Windows (MWW)

       Picture Conversion (PIC)

       PostScript Formatter (PSF)

       WordPerfect 5.x for DOS/Windows (WO)

For all other target formats, a standard character set configuration file (xxstd.cfg) is provided.  xx represents the KEYpak mnemonic of the target conversion module.  There may be additional character set configuration files associated with some target conversions. 

You may view and modify a standard character set configuration file by using any text editor.  It is recommended that only copies of these files be modified.

By default, KEYpak will search for the standard character set configuration file xxstd.cfg in the following order:

1.     Current directory

2.     On one of the search paths

3.     For the environmental variable KW

If the standard configuration file is not found in these locations, only the 95 printable ASCII characters will be contained in the document.  All other characters will be replaced with the character specified by the target configuration “Place marker”.

Source and Target Configuration Files contain source and target configurations which manipulate how the conversion will function.  In general, these files do not need to be specified, as the default values for the configurations are already included in the conversion modules.  If you want to change the values of one or more of these configurations, you can create a configuration file. 

To see the source/target configurations supported by each conversion, refer to the source/target reference files (xxsrc.doc/xxtrg.doc).

Source/target configuration files are passed to the conversion through configuration command line parameters or KEYpak User Interface.  Up to eight configuration files can be specified on the command line. 

For detailed information on creating and using configuration files, refer to chapter 5 of the KEYpak ODX Conversion Reference Guide. 

                        Note                If any of the source/target configuration files is passed to the conversion, it will be necessary to specify the character set configuration file, as KEYpak will not automatically pick up the standard character set configuration file when there is another configuration file specified on the command line.

Option File

An option file is used to pass KEYpak command line parameters.  It is simply a text file.  Each line of an option file is parsed and processed as though it is an extension to the KEYpak command line.  Option files are useful when same type of conversion is executed many times.  In such cases, the special configuration files and various optional parameters remain constant for all similar conversions. 

See chapter 5 “Using KEYpak Command Line” for more information on creating and using option files.

Sample Files

Sample files are included with your installation.  There is one sample file sample.xx for each source conversion format.  xx is the 2 or 3 character KEYpak mnemonic.  If you encounter a problem running KEYpak, use these files to test the KEYpak conversions.

MacBinary File Formats

If you are converting documents that are transferred to and from a Mac, you must use the MacBinary parameters (-bs, -bt, -bf, -bc, etc.) on the command line or in option files. 

For detailed information on MacBinary parameters, see chapter 5 “Using KEYpak Command Line”. 

Splitting Target Documents

Some word processing systems set an upper limit on the size of the documents which can be created or processed.  If the size of the converted document exceeds the target word processor’s limit, KEYpak will automatically split the target document as required into multiple target files.  Names of the additional target files will be based on the name of the original target file, appended with a counter number.