APPENDIX G
VOCAL-EYES .SET UTILITIES

We have included two utility programs on your Vocal-Eyes
program disk, SET2TEXT.EXE and TEXT2SET.EXE.  SET2TEXT.EXE can
take a .SET file and create a standard ASCII text file
containing all the settings of the .SET file.  You can use any
word processor to read through this text file.  Also, SET2TEXT
can be used to globally decompile a list of set files into text
files with corresponding names.  Finally, SET2TEXT can compare
two set files and list the differences between the two in a
standard ASCII text file.  

TEXT2SET.EXE will do the reverse.  It will take a standard
ASCII text file and convert it into a Vocal-Eyes .SET file. 
You can also use the TEXT2SET.EXE utility to make a single
change or a group of changes to many .SET files at one time. 
You could, for example, globally adjust the screen speech rate
to 6 in all your .SET files.  Each utility will be individually
discussed.

SET2TEXT UTILITY

This Utility program enables you to review the contents of your
Vocal-Eyes configuration (SET) files without having to load
them into Vocal-Eyes and wipe out your present speech
configuration.  What does SET2TEXT do?  How does it work? 
Well, the program reads in your Vocal-Eyes SET file and writes
out a "human readable" file which contains all of the
Vocal-Eyes internal settings, hot keys, and various color
attributes.  Every single setting saved with the .SET file is
converted.

To run the program, simply type the following:

SET2TEXT

This will give you a quick summary of what command line options
you need to provide to run the program completely.  To actually
convert a file, use the following format:

SET2TEXT Input file Output file

Input file is the name of the SET file used and maintained by
Vocal-Eyes. Output file is the text file produced by the
SET2TEXT program.  If Output file is omitted, the name of the
Output file will be the same as that of the input file.  This
file can be viewed by any standard ASCII-type text editor or
file viewer such as WordPerfect, VIEW, or Noteworthy.

By default, SET2TEXT will assume an extension of .SET for the
Input file and .TXT for the output file.  For example,

SET2TEXT WP WP
or

SET2TEXT WP

will translate the file WP.SET into the file WP.TXT.  The
original .SET file will not be modified.  Now you can look at
the WP.TXT file to discover all the settings used with WP.SET.

If SET2TEXT could not find the input file, you will get the
error message:

Error:  Cannot open file x

Of course x would be replaced with the actual file name.  If
the input and output file names are the same, SET2TEXT will
change the extension of the Output file to .TXT.

If you issue the command:

SET2TEXT lotus lotus

Assuming the conversion was successful, you will get the
following
message: 
SET2TEXT  Version x.x Copyright (c) 1991-94 GW Micro, Inc.
Written by Steve Holmes and Mike Lawler

LOTUS.SET decompiled to LOTUS.TXT
1 set file was decompiled.

Wildcards can also be used for the set file parameter, so for
example you could decompile all of the Word Perfect set files
with the command

SET2TEXT WP*.*

Note that the parameter for the Output file name is completely
optional and will default to the input "set" file name with the
".TXT" extension if not specified.

SET2TEXT can also be used to compare two Vocal-Eyes set files. 
For example, lets say that you have written a set file for
WordPerfect and you want to compare it with our Word Perfect
set file.  You could use SET2TEXT to convert both files to text
and compare them line by line.  This is both time consuming and
tedious so we have provided the ability for SET2TEXT to compare
two set files and only list the differences between them. In
our example above you could type

SET2TEXT WP OLDWP /C

and SET2TEXT would list the differences between these two set
files in a file called "OLDWP.TXT".  Note that you must use the
above syntax for this to work properly.  The "/C" must be the
last parameter specified to invoke the compare mode of
SET2TEXT.  Also both file names must be specified, but you can
use wildcards to compare several set files to a single
reference set file. For example you could use the following
command to compare all of your set files to VE.SET.

SET2TEXT VE *.SET /C

This would compare all set files with VE.SET and list the
differences in text files with the same names as the set files.

TEXT2SET UTILITY

This utility program basically does the reverse of the SET2TEXT
utility.  It will take a standard ASCII text file created by
SET2TEXT and convert it back to a Vocal-Eyes .SET file.  You
can also globally adjust several .SET files with one ASCII text
file.

If you run TEXT2SET from the command line with no parameters,
you will get a brief description of how to use the program. 
Simply type the following:

TEXT2SET

This will give you a quick summary of what command line options
you need to provide to run the program completely.  To actually
convert a file, use the following format:

TEXT2SET Input file Output file

Input file is the name of the TEXT file produced by SET2TEXT. 
Output file is the .SET file used by Vocal-Eyes.  If the
specified .SET file already exists, it will save the original
values and update only those you specify with the text file. 
That is, the input text file can be abbreviated to contain only
those changes you want.  For example, if you wanted to change
the screen voice rate and nothing else, your input text file
could be as short as one line.

By default, TEXT2SET will assume an extension of .TXT for the
input file and .SET for the output file.  For example,

TEXT2SET WP WP

This would translate the file WP.TXT into the file WP.SET. 
Note that you could also use the command

TEXT2SET wp

and TEXT2SET would assume that you wanted to compile WP.TXT to
WP.SET.

Another very powerful feature with TEXT2SET is the ability to
use "wild card" characters when specifying the .SET file name. 
What this means is you can process one input text file over a
large group of .SET files.  Remember our example of the speech
rate question?  Well, say you want to change the rate in all
your WordPerfect .SET files.  Assuming their names all begin
with WP and have the extension .SET, you could enter the
following command: 
TEXT2SET MYTEXT WP*

The input text file would be MYTEXT.TXT and all .SET files
beginning with "WP" would be updated by TEXT2SET.

If the conversion is successful, you will get something like
this:

TEXT2SET   Version X.X Copyright (c) 1992-94 GW Micro, Inc.
Written by Steve Holmes and Mike Lawler

MYTEXT.TXT compiled to WP.SET
MYTEXT.TXT compiled to WPFILES.SET
MYTEXT.TXT compiled to WPSPELL.SET
MYTEXT.TXT compiled to WPMENU.SET
MYTEXT.TXT compiled to WPREVEAL.SET
5 out of 5 set files were compiled.

Notice how TEXT2SET automatically adjusted all 5 .SET files for
WordPerfect.  It only updated the features found in the file
MYTEXT.TXT.  All commands not specified in MYTEXT.TXT have been
left at their current settings in the individual .SET file.

If you should put invalid Vocal-Eyes options into the input
text file, an error message will be generated.  It will take
the form:

Error TEXTFILE ##: Invalid Vocal-Eyes option

TEXTFILE would be replaced by the name of your input text file. 
## would be replaced by the actual line number inside your text
file that had the error.  Simply use your favorite text editor
and go to the line number mentioned in each error message.

Other error messages may result if you specify invalid values
for Vocal-Eyes options such as speech rate or incorrect key
words such as punctuation level selections and the like.  Where
possible, the error message will display the correct choices
available for that option.

We are sure you will enjoy using these two utilities.  

GW Micro would like to extend our great appreciation to the
authors of these utilities, Steve Holmes and Mike Lawler. 
Steve is not only a user of Vocal-Eyes, but is also a long-time
beta tester for Vocal-Eyes.  When he offered to create these
utility programs, how could we refuse?  Mike, besides being a
Vocal-Eyes user, is on GW Micro's product support staff and has
added numerous features to these powerful utilities.  We feel
these two programs add a great deal to the flexibility of
Vocal-Eyes.  