
tr -- translate strings (EXTERNAL) [v1.2]
      Written by Jeff Ding

syntax:  tr <input pathname> [<output pathname>] -s<search string>
            [-r<replace string>] [-f] [-d] [-w<margin>]
            [-c<number>] [-h<number>]

ex:      tr infile outfile -s^j
         tr infile temp -s^m -r^m^j -fd
         tr infile -s" " -r"" -m60
 
'Tr' looks for every occurrence of the <search string> in the input
file and replaces it with the <replace string>.  The translated data
is saved to the output file.  If the <output pathname> is not specified,
output goes to the screen.  Wildcards are supported.

'Tr' works with any file type, but the input file is always treated as
a raw collection of bytes; no special processing is done for AWP files.
If you use 'tr' on an AWP file, you are not guaranteed to get a valid
AWP file as a result (and if the search and replace strings have
different lengths, you are guaranteed *not* to!).

The search and replace strings are specified in text.  The text normally
has the hi-bits off.  To turn the hi-bit of a character on, use the hi-bit
delimiter, default "~", before the character.  To specify a control
character, use the control character delimiter, default "^", before the
character.  To specify both, use both delimiters in succession; any order
works.  Use "^?" to specify the delete key.  Use "^>" to specify the
control character delimiter.  Use "^=" to specify the hi-bit delimiter.
With these options, it is possible to specify any byte from 0 to 255.

Here are some examples:

  "^j^m"    -  "ctrl-j ctrl-m" (case for control characters is ignored)     
  "~A~B~C"  -  "ABC" with hi-bits on.
  "AbC"     -  "AbC" with hi-bits off.
  "~^m^~m"  -  "ctrl-m ctrl-m" with hi-bits on.
  "^>^="    -  "^~"

Options are as follows:

    output pathname: translated data is saved to this file.  If not
                     specified, output goes to the screen.  The output
                     file type will always be the same as the input file
                     type.

    -s: search string.  (REQUIRED)  See above for description.  This string
        cannot be null.  You must search for at least a 1 byte string.  The
        string can be at most 63 characters long AFTER control characters
        and hi-bit characters are translated.

    -r: replace string.  See above for description.  The string can be at
        most 63 characters long AFTER control characters and hi-bit
        characters are translated.  Omitting this option is the same as
        specifying the null string (matches of the search string are
        replaced by nothing, the null string).

    -f: force overwrite.  Skips the "Okay to overwrite" question if the
        output file already exists.

    -d: delete original.  Deletes the original file and renames the
        output file to the original name.  The output file is needed
        as a temporary storage.  Version 1.1 fixes a bug that caused
        this option not to work.

    -c <ascii number>: determines what character is used for the
                       control delimiter character.  Use the ascii value
                       for the character.

    -h <ascii number>: determines what character is used for the
                       hi-bit delimiter character.  Use the ascii value
                       for the character.

    -w <margin>: wrap margin.  Affects output to the screen only.  This
                 forces a carriage return when either the margin or a
                 space within 9 characters of the margin is reached.
                 Allowed values are 0 through 255.  A 0 value has the same
                 effect as not using the option.

Version 1.2 fixes a bug when the search string was more than one
character long.
