           THE GLOBAL SEARCH AND REPLACE UTILITY (GSR)
                        VERSION 0.2 BETA
                   COPYRIGHT 1996 MARC MULCAHY
                       ALL RIGHTS RESERVED


     Welcome to GSR, the global search and replace utility for the
Braille 'N Speak, Type 'N Speak, Braille Lite, and Braille Lite 40. 
This program allows you to perform simple searches, in which any
occurrences of one string are replaced with another, or, it allows
you to define very complicated search and replace operations with
up to 200 rules in them.  Not only can you perform search and
replace operations on single files, but now, at last, you can
finally use wild cards, and process multiple files with one
execution of the program.  Search and replace rules can be executed
once, or saved in a file for later use.

                     How To Use the Program

In order to use the GSR program, you must first download it into
your unit.  You can do this either by sending it from your PC with
a telecommunications program, or you can download it from a disk
with Blazie Engineering's disk drive accessory.

Once you have downloaded the gsr.bns program into your unit, there
are two ways you can run the program.  You can run it with no
command line arguments, and it will prompt you for all the
necessary information.  You can also specify one or all of the
necessary pieces of information to the program on the command line.

The program needs to know two things in order to run.  First, it
must know the name or names of the files which are to be searched. 
Secondly, it must know the name of the rule file to use.  A rule
file simply gives the program directions, and tells it what to look
for in the files, and what to replace it with if it is found.

If you specify only one file name on the command line, then the
program assumes that you have specified the name of the file to
search, and will prompt you for the name of a rule file.

     By default, GSR performs the search and replace operations on
the original file, but you can tell it to write the output to
another file if you wish.


                      What is a Rule File?

As mentioned above, a rule file tells the GSR program what to
search for in the file or files, and what to replace it with if it
is found.  Rule files are ASCII text files which you can create and
edit on your unit.  Each rule is contained on a separate line. 
Each rule contains two parts:  the search string (what to look
for), and the replace string (what to replace the search string
with if it is found.)  The search string and replace string are
separated by a | character (obtained by pressing dots 1-2-5-6 on
the Braille 'N Speak, Braille Lite, and Braille Lite 40, and a
shift of the back slash on the Type 'N Speak.)  Thus, a rule to
change all occurrences of the word dog in a file to the word cat
would look like this:

dog|cat

You may be wondering how you can include carriage returns in your
strings, or how to include | or control characters in them.  GSR
has a method for putting control characters into your search or
replace strings.  Simply precede the letter of the control
character with a ^ character.  For example, control-m (carriage
return) would be represented by ^m and control-j (line-feed) would
be represented by ^j.  To put a | in a string, use ^| and to put a
^ in the string use ^^.  For example, here is a rule to convert all
carriage returns to carriage return-line feed pairs.

^m|^m^j

Rule files may have up to 200 rules in them, and must be no more
than a page long (4096 bytes).

If you don't want to create your rule files from scratch, GSR has
a facility for creating rule files.  If you don't specify a rule
file name, the program will tell you to enter a rule file name, or
leave blank to create a new rule file.  Simply pressing e-chord on
the Braille 'N Speak, Braille Lite, or Braille Lite 40 (enter on
the Type 'N Speak.) will allow you to create a new file.  GSR will
prompt you for the find and replace strings.  When you are done,
press z-chord (escape on the Type 'N Speak.)  You will be asked for
a file name to save the rules in.  If you don't want to save the
rules, simply press e-chord (enter on the Type 'N Speak), and the
rules will not be saved.


                      Command Line Switches

     GSR has several command line switches to customize its
operation.  These command line switches can be found anywhere on
the command line, and the letters in the switches must be in lower
case.

Search Case Sensitivity

GSR normally performs searches which are not case sensitive.  Which
means that it does not pay attention to the case of letters.  For
example, it would consider the words DOG and dog to be the same.

If you want to force it to perform a case sensitive search (which
means that it will pay attention to the case of letters, specify
the /s switch on the command line.  This tells the program to
perform a case sensitive search.

                Specifying a Separate Output File

     Normally, GSR performs the search and replace operations on
the original file.  If you want to preserve the original file, and
put the results of the search and replace operation in another
file, you can use the /o command line switch.  This switch allows
you to specify the name of an output file where GSR should write
the result of the search and replace operation.  Immediately follow
the /o switch with the name of the output file.  For example, to
process a file called test.txt, and write the resulting file to a
file called test.new using test.rul as the rules file, the command
line would look like this:

gsr test.txt /otest.new test.rul

                       Reverse Translation

     Many times, it would be useful to reverse the direction of the
search and replace rules.  In other words, instead of finding the
"find string" and replacing it with the "replace string", it would
be useful to find the "replace string" and replace it with the
"find string".  For example, consider the following rule file:

^m^j|^m

     This rule file can be used to convert all return-line feed
pairs in a file to carriage returns.  This rule is useful when
downloading files from DOS or UNIX into your unit.  After editing
the files in your unit, however, you may wish to convert the
carriage returns back to carriage return-line feed pairs, so the
files can be used on a DOS or UNIX machine.  And, it would be
useful to be able to do this without rewriting the rule file.  This
is where the /r command line switch is used.  The /r command line
switch tells GSR to perform the search rules in reverse (I. E.
search for the "replace string", and replace it with the "find
string.)


