

                BINARY FILE LANGUAGE TRANSLATOR             Page 1



       XLAT 0.1,  1990 Graham Steel


       1  Nomenclature

       XLAT  0.1  is  a simple menu-driven utility designed for translating
       binary  files (programs and resource files) from German into English
       on  the  Atari ST. The author maintains copyright to the program and
       this  accompanying  documentation;  however,  both may be copied and
       used  freely, provided that the program is not used to translate the
       credits within itself in any manner whatsoever.


       1.1  Disclaimer

       The author beleives that XLAT is an Xellent program, but will not be
       held responsible for any problems caused by programs which have been
       translated  in full or in part by XLAT. A binary file may consist of
       both text and code; but the computer running the program is not very
       aware  of the difference. Neither is it always obvious, when looking
       at  the binary file, where the text stops and the code begins. There
       is therefore no guarantee that upon translating what appears to be a
       word of text, the program will still work.


       1.2  Credits

       Version  0.1  of the program was developed Graham Steel in July 1990
       on  an Atari STE. The program source is written in 'C', and compiled
       using the Sozobon compiler. This documentation was prepared using ST
       Writer ( 1988 Atari Corporation).


       2  Using XLAT


       2.1  Requirements

       XLAT  0.1 consists of two files, XLAT.TTP and GERMAN.DIC. The latter
       must be present in the current working directory (important if using
       XLAT.TTP  from  a  command  line  interpreter).  It is intended that
       future  versions of XLAT will support other languages. However, XLAT
       0.1  reads  only  the  first  line of GERMAN.DIC (the alphabet), and
       other  languages may be handled by editing this line to the alphabet
       of the desired language.


       2.2  Invocation

       XLAT  0.1  is a TOS-Takes-Parameters type program. If double-clicked
       from a desktop, a dialogue box will appear asking for parameters. If
       invoked  from  a  command  line  interpreter  (such  as  Gulam), the
       parameters  must  be provided on the invocation line. XLAT 0.1 takes
       only one parameter: the name (or path) of the file to be translated.








                BINARY FILE LANGUAGE TRANSLATOR             Page 2



       There  are no rules concerning the format of this file or path name,
       provided  that  it  is  a legitimate TOS file or path name. However,
       XLAT 0.1 automatically creates a backup of any translated file, with
       the  same  name  as  the file to be translated but with the extender
       ".OLD".  Therefore,  files  which already have an extender or ".OLD"
       should  not be used. After use, assuming that translation is carried
       out  and  the  translated  file is saved, the new file will have the
       original  file name, whilst the original file will have been renamed
       to ".OLD".

       Example: to translate a file "GAME.PRG".

         1. From the desktop, double-click XLAT.TTP and type GAME.DOC,
            <Return>; or,
            From a command line interpreter, type
                          XLAT.TTP GAME.DOC <Return>.

         2. Follow the menus to perform the desired translations.

         3. Use 'S' to save, and 'Q' to finish XLAT.

       The  original  file  will  now  be  called  "GAME.OLD",  whilst file
       "GAME.PRG" will contain your new version.


       2.3  Loading

       XLAT 0.1 immediately displays its version and copyright sign:

           XLAT 0.1 (binary file language translator),  Graham Steel 1990

       It  then  proceeds to read the dictionary (GERMAN.DIC). Normally the
       message

           Reading dictionary ... Done

       will be displayed. If a problem is encountered, the message

           Reading dictionary ... Failed to open GERMAN.DIC

       will  be  displayed  instead.  In  this  case  you should reread the
       section  entitled  "Requirements"  above,  check the presence of the
       dictionary, and try again.

       Once  the  dictionary has been successfully loaded, XLAT 0.1 goes on
       to  load  the  specified  file  to be translated. If no filename was
       provided  as  a  parameter, the current version of XLAT will ask for
       the filename to be entered at this stage with the prompt

           Translate file:

       whereupon  you  should  type  the  desired  name, and <Return>. This
       feature  may be removed in future versions: the filename is supposed
       to  be  provided as a parameter. The loading of the file is normally








                BINARY FILE LANGUAGE TRANSLATOR             Page 3



       accompanied with the message

           Loading GAME.PRG ... Done

       (if GAME.PRG is the file to be translated). If there are problems in
       loading, one of the following messages will be displayed:

           Can't find file          (the specified file does not exist)
           Cannot open GAME.PRG     (the file does exist, but there are
                                     other reasons why it cannot be
                                     loaded)
           Out of RAM               (the file is too big to be loaded.
                                     Remove your accessories, RAM disk,
                                     etc, and try again. Or buy a RAM
                                     upgrade)
           Cannot read GAME.PRG     (the file was successfully opened, but
                                     failed to load. Possible corruption)


       2.4  Menus

       XLAT  0.1 is menu-driven. There are two menus: the Main Menu and the
       Parameters  Menu.  The  appropriate  menu is redisplayed each time a
       response  is  required,  and the response takes the form of a single
       letter  (as shown within the parentheses in each menu). Either upper
       or  lower  case  letters  may  be  used to respond to the menu. If a
       character  other  than  those  specified  in  the menu is typed, the
       message

           Command not recognised

       is displayed.

       The  Main Menu is displayed after the file to be translated has been
       successfully  loaded,  and after each operation until the Parameters
       Menu  is  selected  or  you  opt  to quit. The Main Menu offers five
       operations as follows

           (L)ist strings,  (T)ranslate string,  (S)ave file,
           set (P)arams,  (Q)uit

       The  Parameters  Menu  is displayed when 'P' is typed in response to
       the   main  menu,  and  after  each  operation  performed  from  the
       Parameters  Menu  until  you  opt  to  return  to the Main Menu. The
       Parameters Menu offers three operations as follows

           Set (S)hortString length, Set case (F)ixing, (M)ain Menu


       2.5  Operations


       2.5.1  (L)ist Strings









                BINARY FILE LANGUAGE TRANSLATOR             Page 4



       XLAT  0.1  attempts  to  display all ascii strings within the binary
       file.  Of  course, XLAT cannot really distinguish ascii from program
       code and binary data; so it guesses that all strings of four or more
       ascii  characters  are textual and displays these. The limit of four
       characters  may  be changed: see "Set Params" below. The strings are
       displayed  through  a UNIX "more" style filter; if the screen fills,
       the  prompt  "--More--"  is  displayed, and you may type <Space> for
       another  screenful,  <Return>  for  another line, or 'Q' to halt the
       display and return to the Main Menu.

       Ascii characters are considered to be those with values in the range
       20  to  7E hexadecimal, plus any characters outside that range which
       are  defined  in  the alphabet in the file GERMAN.DIC. Hence, if you
       wish  to  list  the  strings  of  a French file, you should edit the
       alphabet in GERMAN.DIC accordingly.


       2.5.2  (T)ranslate String

       Having established the strings that you wish to translate, either by
       running  your foreign language program and making a note of them, or
       by  using the ListStrings operation above; you use this operation to
       perform the substitutions. XLAT 0.1 prompts with the message

           Old string:

       whereupon  you  should  type  the  German  string (or whatever) that
       appears in the file to be translated, and <Return>. XLAT 0.1 is case
       insensitive,  so  "LAUFWERK"  will  match  "Laufwerk"  or "laufwerk"
       without problems. The prompt message

           New string:

       will  then  be  displayed, to which you may type "Floppy Disk Drive"
       <Return>.  XLAT  0.1 will then substitute ALL occurrences of the old
       string  with the new one. However, there are a couple of clever bits
       to  bear in mind. Firstly, since this is a binary program file, XLAT
       0.1  considers  it  safe only to substitute strings of equal length.
       Hence,  if  your  new  string  is  longer  than  the old, it will be
       truncated  from  the  right;  and if it is shorter, it will be right
       padded   with   spaces.  The  second  clever  bit  applies  only  to
       substitutions of single words, never to substitutions of two or more
       words.  For  each  occurrence  of the old word in the file, XLAT 0.1
       will  attempt  to  determine whether it is all lower case, all upper
       case,  or  capitalised  (beginning  with a capital letter); and will
       manipulate  the  new  word accordingly. If XLAT 0.1 cannot determine
       the  case  of  the old word (because upper and lower case characters
       are  jumbled)  or  if groups of words are being substituted, the new
       string  will be written into the file without case manipulation. The
       case  manipulation  may  be  completely  turned  off:  see "Set Case
       Fixing"  below.  After  performing a substitution, XLAT 0.1 displays
       the message

           4 replacements done








                BINARY FILE LANGUAGE TRANSLATOR             Page 5




       (if four occurrences of the old word were found and replaced).


       2.5.3  (S)ave

       Substitutions  carried  out  using the Translate operation above are
       performed  within  memory.  You must use the Save operation to write
       the file back to disk. Each save operation renames the original disk
       file  (or  the  previously  saved  version) to GAME.OLD (if you were
       translating the file GAME.PRG).

       IMPORTANT:  a  file may be saved more than once during an invocation
       of  XLAT  0.1;  the  final  version  of  the file always carries the
       original  file  name,  whilst  the  immediately  previous version is
       backed  up  to the ".OLD" file. Therefore, upon the second save, the
       original file will be lost. Make your own backup before starting, if
       required.  Note  also  that  whilst  XLAT  0.1  never  saves the new
       translation  of  a  file unless explicitly requested, will not allow
       you  to  quit  without  saving without first confirming that this is
       what you want to do.

       The  first  part  of  the save operation is to create the backup. If
       this fails, the message

           Can't create backup GAME.OLD

       is  displayed.  You should stop and examine why. Be prepared to quit
       the  translation and start again if necessary. Maybe it is just that
       your disk is write protected.

       Having  created  the backup, the newly translated file is written to
       disk. If this fails, one of the messages

           Cannot open GAME.PRG (nn)
           Cannot write GAME.PRG

       will  be  displayed  (where nn is a decimal error code). Again, stop
       and examine why. Your disk may be full.


       2.5.4  (Q)uit

       This  operation  is  the  means of exiting XLAT 0.1. If you have not
       changed  your file, or have already saved all changes; XLAT 0.1 will
       immediately  exit.  If  there  are  unsaved  changes,  XLAT 0.1 will
       display the message

           Quit without saving?

       to  which  you  should  type  either  'Y'  or  'N'. XLAT 0.1 is case
       insensitive  here; but anything other than 'Y' or 'y' is interpreted
       as meaning "no", and the Main Menu is redisplayed.









                BINARY FILE LANGUAGE TRANSLATOR             Page 6



       2.5.5  Set (P)arameters

       This operation allows you to access the Parameters Menu.


       2.5.6  Set (S)hortString Length

       This  parameter  controls the activity of the ListStrings operation.
       The following message will be displayed

           Currently, strings of 4 or more characters will be displayed by
           'List Strings'. Enter new minimum length

       If you have tried listing the strings, and XLAT 0.1 displays a whole
       load  of  gibberish  along  with  the  strings;  try  increasing the
       ShortString  length  to  make  it less sensitive. Type a number, and
       <Return>.  Conversely,  if  you  know  that your file contains short
       words  which  are  not being displayed by the ListStrings operation,
       try decreasing this number.


       2.5.7  Set (C)ase Fixing

       XLAT  0.1  performs  intelligent  case  fixing  for substitutions of
       single words, as described for the Translate String operation above.
       You  may  disable  this  function  (and re-enable it) using the Case
       Fixing operation. XLAT 0.1 will display either

           Currently, the program will attempt to make the case of single
           word replacements match the case of the word to be replaced
           Do you want intelligent case fixing (Y/N) ?

       or

           Currently, the program will not attempt to change the case of
           single word replacements
           Do you want intelligent case fixing (Y/N) ?

       You should type 'Y' to enable the case fixing, or 'N' to disable it.
       XLAT  0.1  is  case insensitive here, but if you type anything other
       than 'Y' or 'N' it will repeat the prompt.


       2.5.8  (M)ain Menu

       This  operation allows you to return from the Parameters Menu to the
       Main Menu.


       3  Planned/Desired updates

       The following functionality and additional operations may or may not
       be incorporated into future versions of XLAT:









                BINARY FILE LANGUAGE TRANSLATOR             Page 7



         -  Other  languages  should  be  supported.  The  program would be
       invoked
           as
                XLAT -FRENCH GAME.PRG
           in  order  to  load  the  dictionary  FRENCH.DIC  instead of the
       default
           GERMAN.DIC.

         - The dictionary should be read from the path containing XLAT.TTP
           rather than from the current working directory.

         - The dictionary should contain a list of pairs:
           (German  word,  English  translation),  and  XLAT should have an
       auto
           translate operation.

         -  There  should  be  a  query-replace  operation  as  well as the
       current
           global Translate String operation, in which the context of each
           Old String is displayed and the user types 'Y' or 'N' (or 'Q').

         -  There should be no ListStrings operation. The strings should be
       on
           display  all  the  time,  in  a  window  which  can be scrolled.
       Ideally,
           the menus should be abolished and the whole program be GEMmed.

         -  The copyright sign within XLAT.TTP should be encrypted, so that
       the
           program cannot be used to edit the credits within itself.


                     Graham Steel
                     154 Station Road
                     Ratby
                     Leicester LE6 0JP
                     United Kingdom                August 1990























