

----------------------------------------------------------------
|                                                              |
|                 AAA    NN   NN   SSSSS   IIII                |
|                AA AA   NNN  NN  SS        II                 |
|               AA   AA  NNNN NN   SSSSS    II                 |
|               AAAAAAA  NN NNNN       SS   II                 |
|               AA   AA  NN  NNN  SS   SS   II                 |
|               AA   AA  NN   NN   SSSSS   IIII                |
|                                                              |
|                           LL                                 |
|                            L         T                       |
|          EEE  MM M  U   U  L   AAA  TTT  OOO  RRRR           |
|         E   E M M M U   U  L      A  T  O   O R   R          |
|         EEEEE M M M U   U  L   AAAA  T  O   O R              |
|         E     M M M U   U  L  A   A  T  O   O R              |
|          EEE  M M M  UUUU LLL  AAAA   T  OOO  R              |
|                                                              |
|                                                              |
|               version 0.03 / preliminary version             |
|                                                              |
|                                                              | 
|                   (C) 28-Feb-1993  BoLuSoft                  |
|                                                              |
----------------------------------------------------------------



   What you should have
   --------------------
   In the distribution archive you should find following files:

ANSI_002.ZIP
 - ANSI_000.TOS ... Programme file for all Atari computers
 - ANSI_020.TOS ... Programme file for TTs or upgraded machines
 - ANSI.TXT     ... This document
 - ANSI.TST     ... Test text with ANSI-sequences
 - ANSI.CPX     ... CPX-module (for XControl, for all machines) 
 - HISTORY.TXT  ... History of changes

   If something is missing,  then obtain new archive or  contact 
me personally. Address is given below.



   What is ANSI emulator for?
   --------------------------
   As you may know,  Atari computers' BIOS  has  VT-52  emulator 
incorporated in it.  This allows application to do some  actions 
concerning  text  output  quicker  and  simplier.   VT-52  codes 
contains  sequences for cursor movement,  screen erases in  many 
ways  and  so  on.   Atari  has  extended  VT-52  by  codes  for 
controlling colour and some others.  Unfortunately, VT-52 is not 
the most widely used standard for terminal emulation in  today's 
world.  The  main standard used mostly on  computers  compatible 
with  IBM  PC is called ANSI.  This standard  is  normalized  by 
ANSI,  but on PCs there's often implemented only subset of  real 
ANSI  definition.  In some cases you would need to emulate  ANSI 
terminal.  The  most  common  case is  communicating  with  host 
machine   which   sends  such   ANSI   codes.   Normally,   when 
communicating  with  computer using ANSI,  the screen  would  be 
quickly  full  of  strange characters  those  could  even  avoid 
reasonable work.  But here's ANSI emulator now. It is residently 
installed  in memory and translates all ANSI sequences into  VT-
52, which are understood by Atari computers.



   Hardware requirements
   ---------------------
   ANSI  emulator now works on all Atari computers, although the 
version for processor M68020 is still supplied. It was primarily 
intended  to run on Atari TT computer in 640x480x16  resolution, 
but it will work in any other TT or ST resolution.  When running 
on upgraded Atari ST(e) you cannot enjoy full 16-colour range of 
TT-middle resolution.



   Software requirements
   ---------------------
   ANSI  emulator should run on all TOS-version  from  1.06.  It 
needs Cookie Jar to be installed. This requirement is met on all 
new Atari computers.  If you have machine with TOS < 1.04,  then 
you  can  use  some  programs installing  Cookie  Jar  on  older 
machines (one is Atari-Profibuch from J.  Reschke).
   The second requremenet is,  that  in Cookie Jar SHOULD be  at 
least one slot free. When there's no free place for ANSI cookie, 
then warning is issued,  but ANSe will install itself,  but  you 
cannot use CPX-module (as it uses ANSI-cookie).
   Version for 68020 needs to find '_CPU' cookie to ensure it is 
running on real 68020 or higher.  If '_CPU' cookie is not found, 
it will refuse to install itself.   



   Installation
   ------------
   You can install ANSI in two ways: running it from desktop, or 
running from AUTO folder.  Running from AUTOfolder requires  you 
to rename it to PRG.  It is not possible to install it more then 
once. NOTE! that ANSI emulator is deinstalled on each resolution 
change!



   CPX-module
   ----------
   CPX-module allows you to affect ANSe's operation in after  it 
is  installed.  This requires you to use Atari's  XControl  (you 
should use it,  anyway,  because it is very useful  thing).  You 
install  it by copying ANSI.CPX to folder where you  have  other 
CPX's.  After  next  boot  or after reloading  CPXs  (from  menu 
Options on front panel) you will have it ready to use. CPX will, 
of course,  work only if ANSe is already installed; otherwise it 
will display an alert.
   In left pane of ANSe.CPX you see three shaded  buttons.  When 
you click on them,  small pop-up menu appears.  I  hope,  you're 
familiar  with this type of controls.  If not,  try it  out,  it 
quite simple!
   The buttons are marked:

Switch: { On | Off }

This can be,  like normal switches, switched on or off. When you 
set  it 'on',  ANSe will work accordingly to the other  buttons. 
When you choose 'off',  ANSe won't do anything.  By this you can 
temporarily  suppress  emulating ANSI  sequences,  eg.  when  it 
causes problems.

Mode: { Emulate | Filter }

This button affect the way ANSe emulates ANSI-codes.  When it is 
set  to  'emulate',  it  will try to  emulate  all  known  ANSI-
sequences.  When you set it to 'Filter', it will only filter out 
all  ANSI-sequences,  but  won't emulate  them.  You  won't  see 
colours,  screen clears won't be performed and so.  This can  be 
very  useful in case the colour palettes of host and client  are 
matching  badly.  You can continue to work,  but there'll be  no 
black letters on black background. ;-)

Inverse: { On | Off }

If  you have ever worked with PC (God be with you ;-)  then  you 
know,  that normally PCs display white letters on black  screen. 
On  the  other hand,  Atari computers usually  work  with  black 
letters on white background. This may cause problems, eg. yellow 
letters  look  good  on PC,  as they are  on  black,  but  being 
displayed on Atari this can be only hardly read, because they're 
on white. So, when you switch this buton on, then ANSe will swap 
black and white colours whenever met.

   On the right, smaller pane of CPX-dialog you have little info 
about how much ANSI sequences was emulated so far;  and how many 
unknown sequences was met.  Normally, the first number should be 
higher then the second ...



   Technical issues
   ----------------
   ANSI  emulator  installs itself on vector  bconout[2]  ($58E) 
using  XBRA id 'ANSe'.  Note that this vector is  replaced  upon 
each  resolution  change when you're  using  NVDI.  This  causes 
deactivating ANSe.  I think,  that it is bug of NVDI, so I'm not 
going  to  do some ferocious manipulations with stack  to  avoid 
NVDI's problems.
   Furthermore, ANSI emulator installs cookie 'ANSI'. It's value 
is pointer to following structure:

  typedef struct {
    long  ANSe_id;    /* identification='ANSe'            */
     int  ANSe_ver;   /* version=$0002                    */
    long  ANSe_cnt;   /* number of ANSI-seqences emulated */
    long  ANSe_err;   /* number of unknown ANSI codes met */
     int  ANSe_flags; /* internal flags                   */
     int  ANSe_emul;  /* bit 0 - enable/disable ANSe      */
                      /* bit 1 - emulate/filter only      */
  } ANSE_INFO;        /* bit 2 - inverse/normal mode      */

   Look in description of CPX-module for more info.

   When there are not 16-colours available, emulator does colour 
conversion (which is pretty stupid now). But it can never happen 
that foreground and background colours are same.

   ANSe was develped using HiSoft Devpac 3.



   ANSI sequences supported
   ------------------------

ESC[ <n> A ............... Cursor up
ESC[ <n> B ............... Cursor down
ESC[ <n> C ............... Cursor right
ESC[ <n> D ............... Cursor left
ESC[ <y>;<x> H ........... Cursor position
ESC[ <y>;<x> f ........... Cursor position
ESC[ <y>;<x> j ........... Cursor position
ESC[ s ................... Save cursor position
ESC[ u ................... Restore cursor position
ESC[ <n> J ............... Erase display
ESC[ K ................... Erase line
ESC[ <n>;<n>;...;<n> m ... Set Graphics Rendition for 
                             n=0 - reset
                             n=1 - inverse on
                             n=7 - bold on
                             n=<30;37> - foreground colour
                             n=<40;47> - background colour

    All other ANSI escapes are ignored,  but not sent  to  VT-52 
emulator (you won't see them).



   Legal
   -----
   ANSI emulator is  freeware.  If you are interested  in  newer 
versions then send a (net)mail to register.



   Author's address
   ----------------
   Borek Lupomesky
   Marvanova 4
   Usti nad Labem, 400 12
   Czech Republic
   tel/TAD: +42-47-45816 (only weekends)

   E-mail: Borek Lupomesky on 2:423/71@fidonet.org

------------------------ T H E   E N D -------------------------

