VoiceCode 1.0 installation guide
Last updated 15 October, 1996

Contents
1. VoiceCode requirements 
2. Installing VoiceCode 
2.1 Steps in the installation procedure 
2.2 Restoring the files 
2.3 Installing the vocabulary compiler 
2.3.1 Installing perl5 
2.3.2 Installing the perl scripts 
2.3.3 Testing the vocabulary compiler 
2.4 Installing the editor macros (Emacs users only) 
2.5 Installing the DragonDictate macros 
2.5.1 Moving the macros to the local machine 
2.5.2 Importing the macros into DragonDictate 
2.5.3 Customizing the macros for your setup 
2.5.3.1 Customizing for file transfer mode 
2.5.3.1.1 Transfer through file system mounting 
2.5.3.1.2 Transfer through FTP 
2.5.3.2 Customizing for the editor used 
2.5.4 Copying the macros to application vocabularies 
 

1. VoiceCode requirements
This section describes the various requirements that must be met to be able to use the VoiceCode package.
VoiceCode is designed to work in a distributed setup where you run DragonDictate on a PC (referred to as the local machine) to edit source files located on a Unix machine (referred to a the remote machine). It is assumed that there is a means of transferring commands from the local machine to the remote machine (using a2x or an X terminal emulation software like Exceed) as well as a means of transferring files from the remote machine to the local machine (either by mounting the file system of the remote machine on the local machine, or through FTP).
The VoiceCode package consists of a perl script called the vocabulary compiler, and some DragonDictate and editor macros designed to integrate it into your work environment. 
If you want to run the vocabulary compiler from the command line, the only requirement is that you must be programming on a Unix machine which can run perl5. A port of the vocabulary compiler to Win 3.1, Win 95 and Windows NT is on the way to make VoiceCode usable by people programming on those platforms. 
If you want to run the vocabulary compiler in a way that is more integrated with your environment, you need the following additional requirements:  
* Emacs or vi editor
* DragonDictate running on Windows NT, Windows 95 or Windows 3.1
* If you are running DragonDictate on Windows 3.1, you need to have some automated way of transferring files from the remote machine to the local machine (e.g. transparent mounting of the remote file system or scriptable FTP program on the local machine).
If one or more of the later are not met, you may still be able to integrate the vocabulary compiler into your work environment by modifying some of the macros included in the VoiceCode package
2.  Installing VoiceCode
2.1 Steps in the installation procedure
 Installation of VoiceCode is broken down into three major steps:
* uncompressing the file
* installing the vocabulary compiler
* installing the editor macros (Emacs users only)
* installing the DragonDictate macros
These steps are described in the following sections.
2.2 Restoring the files
The first step is to restore the files which you downloaded. You must first decompress the file with gunzip, then extract the files using the tar command. 
2.3  Installing the vocabulary compiler
The next step is the installation of the vocabulary compiler on the remote machine. This is described in the following section.
2.3.1 Installing perl5
Before you install the vocabulary compiler, you must have a version of perl5 installed on your remote machine. Versions of perl5 can be obtained from the NetLabs ftp site (ftp://ftp.netlabs.com/pub/outgoing/).
2.3.2 Installing the perl scripts
To install the vocabulary compiler, simply copy the content of the VocComp directory to a new location on your remote machine. You must also set an environment variable VCHOME on your remote machine to be the path of this directory.
IMPORTANT: Make sure that you do not end the VCHOME environment variable with a slash "/".
Next, you must modify the first line of the perl scripts $VCHOME/vocCompile.pl and $VCHOME/Benchmark/doBenchmark.pl to be the following:
#!<perl5 path>
where <perl5 path> is the path of the perl5 executable on the remote machine.
2.3.3 Testing the vocabulary compiler
You can test the installation of the vocabulary compiler by running the script $VCHOME/Benchmark/doBenchmark.pl . The output of this script should be identical to the file $VCHOME/Benchmark/Results/benchmark.log, with the exception of a few lines starting with one of the following:
***
Compiling vocabulary for file
add-word "[VoiceCode]" /keys "VoiceCode"
2.4 Installing the editor macros (Emacs users only)
If you are an Emacs user, you need to load some Emacs Lisp macros to make it possible to invoke the vocabulary from within your editor.
To load these into Emacs, simply add the following line to your .emacs file:
(load (substitute-in-file-name "$VCHOME/compileBuffer.el"))
then exit Emacs and restart it.
2.5  Installing the DragonDictate macros
The final step is the installation of some DragonDictate macros to allow invoking the vocabulary compiler through the utterance of vocal commands. This is described in the following section.
2.5.1 Moving the macros to the local machine
Move the directory DDMacro to a directory on your local machine. This will be referred to as the "local VoiceCode directory". Note that this directory must be a valid DOS directory, that is, the path of the directory must be made up of subdirectories whose names contain at most 7 characters. This is necessary even if you are running DragonDictate on Windows 95.
2.5.2 Importing the macros into DragonDictate
The next step is to import the file voicecod.ddx  (located in your local VoiceCode directory) into DragonDictate using the vocabulary manager. This will create a new vocabulary VoiceCode-Macros and will add the following macros to your Voicebar/Add Word vocabulary:
* [<VoiceCode-Macros/Join Operation> <Number/1 to 9>]
* [Copy Key Strokes]
2.5.3 Customizing the macros for your setup
You need to make some minor modification to the [Load Vocabulary] macro in order to customize it to your personal setup. This is the macro that you use to tell your editor to compile a vocabulary for the file, project or directory which you are currently editing. 
All those modifications involve editing the script for[Load Vocabulary] and modifying the values of one or more of the configuration variables which are initialized at the very beginning of that script. 
Below are descriptions of the various changes you may need to make.
2.5.3.1  Customizing for file transfer mode
When you invoke the [Load Vocabulary] macro, it sends a sequence of keystrokes to your editor that causes it to compile the file, directory or project you are currently editing. This results in the creation of a vocabulary file on the remote machine. Before [Load Vocabulary] can import this file into DragonDictate, it must first transfer it from the remote machine to the local machine. This can be done in two ways.
The recommended way is to mount the file system of the remote machine on the local machine. This way is best because it makes the transfer process invisible to the user. However not all machines are equipped with software that allows mounting of a remote machine's file systems. 
If you cannot mount the file system of the remote machine, you can use an FTP script. This will be possible on most machines, but it will require the user to pronounce one more utterance in order to start the file transfer. 
Below is the description of the changes that need to be made in both cases.
2.5.3.1.1 Transfer through file system mounting
 If you are using the file system mounting setup, you must set the following configuration variables:
transferMode = "m"
mountedVoiceCode = <mounted path>
where <mounted path> is the path of the VoiceCode home directory on the remote machine * as it appears to your local machine *. 
IMPORTANT: Make sure that you do not end <mounted path> with a "\".
Note that <mounted path> must be a valid DOS path, that is it must be made up of subdirectories with at most 7 characters. If the path of the VoiceCode home directory on your remote machine is not a valid DOS path, you can alleviate the problem by mounting the remote machine's file system starting at the root of the VoiceCode home directory.
 For example, suppose the path of the VoiceCode home directory on your remote machine is /home/ksl00/alain/VoiceCode/. This is not a valid DOS path because the subdirectory VoiceCode has 8 characters. What you can do then is to mount the directory /home/ksl00/alain/VoiceCode on say the g: drive of your local machine and set 
mountedVoiceCode = g:\
2.5.3.1.2  Transfer through FTP
If you are using the FTP setup, you must set the following configuration variables:
transferMode = "f"
localVoiceCode = <local VoiceCode directory>
ftpCommand = <FTP command>
where <local VoiceCode directory> is the directory you created on your local machine at step 2.5.1 and <FTP command> must be a command that transfers a file $VCHOME/Load/new.ddx from you local machine to the path <local VoiceCode directory>\Load\new.ddx.
IMPORTANT: Make sure that you do not end <local VoiceCode directory> with a "\".
If you are running DragonDictate on Windows 95 or Windows NT, you can implement this command using the bundled ftp program. You do this by setting ftpCommand to:
ftpCommand = "ftp -s:" + localVoiceCode + "\ftpScrp"
and creating an ftp script file <local VoiceCode path>\ftpScrp containing the following commands:
open <remote machine address>
<user name>
<password>
binary
lcd <local VoiceCode directory>\Load
cd <remote VoiceCode directory>/Load
get new.ddx
close
quit
where:
<remote machine address>	: the IP address of your remote machine
<user name>	: name of an authorized user on the remote machine
<password>	: password for that user name
<remote VoiceCode directory>	: explicit path of the VoiceCode home directory on the remote machine (you cannot use the $VCHOME environment variable here).
2.5.3.2 Customizing for the editor used
If you are using the Emacs editor, you must set:
editor = "emacs"
If you are using the vi editor, you must set:
editor = "vi"
In the later case, you must also modify the [Load Directory Vocabulary] macro. Any modification you made to [Load Vocabulary] must be repeated here.
2.5.4 Copying the macros to application vocabularies
In order to use the DragonDictate macros provided with VoiceCode, you must copy them to the vocabulary of every application in which you might want to dictate some special expressions. If there are many such applications you might consider copying them to the System/Global vocabulary instead.
For each window of each application where you might want to dictate special expressions, you must also add the name of the application to the VoiceCode-Macros/Applications vocabulary and the title (or the beginning of the title) of the window to the VoiceCode-Macros/Windows vocabulary. 
For example, if you want to be able to dictate special expressions in an Exceed window displaying the Emacs editor with title "emacs19@ksl1000.ai.iit.nrc.ca", you would have to add "Exceed" to the VoiceCode-Macros/Applications vocabulary and "emacs" to the VoiceCode-Macros/Windows vocabulary.
7


7



