Brief documentation for TOS2GEM dated 26.07.1995, position at 03.08.1995
========================================================================

 1. What is TOS2GEM?
 -------------------
 TOS2GEM is an Auto folder program which GEM applications can access in 
 a flexible way to display the output from TOS and TTP programs as VDI 
 text in a Console window.
 TOS2GEM makes the ideal Console window for use with shells or alternative 
 desktops and saves the programmer some effort!

 TOS2GEM was principally designed for use under Single TOS and although it 
 runs fine under Geneva, MagiC and MultiTOS its use there is limited as 
 under these systems TOS programs run in windows anyway (if they have been
 started correctly).

 The most important TOS2GEM features at a glance:
 - Gives prorammers a clean way of redirecting the output of TOS/TTP type 
   programs into a GEM window.
 - Simulates TOS screens of various sizes (not just boring 80x25) that may 
   optionally be only partly visible.
 - Works with all monospaced fonts irrespective of size.
 - Optional output buffer allows faster output than with GEMDOS/BIOS (only
   for SingleTOS/MagiC).
 - Optional scroll-back buffer allows output to be reviewed.
 - Offers almost complete VT52 emulation (colour sequences optional only)


 2. Installation
 ---------------
 Copy TOS2GEM.PRG to the Auto folder of your boot partition. TOS2GEM 
 installs a Cookie during booting which programmers can use to control 
 some of TOS2GEM's functions. TOS2GEM.PRG can also be run from the desktop.
 

 3. What is T2GRESET.PRG?
 ------------------------
 Programs must reserve TOS2GEM for themselves; until released other 
 programs cannot make use of TOS2GEM.
 If a program which had reserved TOS2GEM crashes or is exited without 
 releasing TOS2GEM, you can use T2GRESET.PRG from the desktop to release 
 TOS2GEM. It's not a good idea to run T2GRESET.PRG if an application 
 which has reserved TOS2GEM is still running, as this inevitably causes 
 serious complications.
 Signs that a lock-up has taken place are if no program using TOS2GEM will
 run, and a newly-started one reports that it cannot make a reservation.


4. What is T2G_INTR.PRG?
 ------------------------
 Since the beta-version dated 09.07.1995, TOS2GEM uses the vertical-blank 
 interrupt during time-controlled buffering to trigger screen refreshes 
 even when there has been no TOS-output for some time (previously checks 
 for exceeding the given period were only made during output). If this 
 should unexpectedly lead to problems (e.g. unexplained crashes while 
 output redirection is active), one can use T2G_INTR.PRG to switch off the 
 use of this interrupt (and to switch it on again, if desired, by running 
 the program a second time). If one wishes or needs to disable the use of 
 the VBL interrupt permanently, then T2G_INTR.PRG should be placed 
 physically after TOS2GEM.PRG in the AUTO folder.

 Important: Those who have previously included the mini-package of TOS2GEM 
 (see Section 9) with their programs mustn't overlook the fact that 
 T2G_INTR.PRG has now been included in this package!
 
 
 5. What are T2G_TEST.PRG and PRIME_NO.TOS? 
 ------------------------------------------
 (These have been renamed from the German T2G_BSP.PRG and PRIMZAHL.TOS so 
 that the titles indicate their purpose better to English-speaking users).
 Since it is difficult to visualise from the theoretical description of 
 TOS2GEM operation what the program actually does, I wrote a small test 
 program (namely T2G_TEST.PRG, meaning TOS2GEM-test). These two programs 
 are incidentally not contained in the mini-package (see Section 9).

 After starting the test program (TOS2GEM must of course have been started 
 first) a dialog box appears in which one can input the dimensions of the 
 TOS screen that TOS2GEM is to simulate, and the maximum area that is to 
 be visible. One can also choose here whether and how output buffering and 
 colour support of TOS2GEM is to be used. Following this a corresponding 
 window will be opened (already using the TOS2GEM redirection) into which 
 the realised dimensions will be written.

 Immediately after this the PRIME_NO.TOS program (that has to be in the 
 same directory) will be started; it can execute simple prime number 
 calculations using the 'Sieve of Eratosthenes' method (one can also use 
 any other TOS program, it just has to be re-named to PRIME_NO.TOS and 
 placed in the correct directory). To use it, just follow the prompts; 
 note that you have to type 'j' for 'Yes' (which in German is 'ja').

 After ending the prime number program one can move the window, into which 
 the output was redirected cleanly, around the screen. Clicking on the 
 Closer symbol at top left quits the program. A click inside the window 
 area brings up an alert box offering three options: 'Resize' permits 
 altering the TOS2GEM window area (with the same dialog that appeared at 
 the start; during this the whole screen will be cleared if its total size 
 is changed). With 'Rerun' one can start PRIME_NO.TOS again, while 
 'Nothing' does just that...

 The test program has been kept simple deliberately, partly so one can see 
 that TOS2GEM support is quite easy to realise. Not all the options of 
 TOS2GEM are demonstrated (in particular, neither multiple fonts in 
 various sizes are used nor is a scroll-back buffer implemented), but 
 there should still be enough to illustrate the opportunities that TOS2GEM 
 offers.

 Those who would like to have the source code in order to get a concrete 
 picture of what TOS2GEM support involves should apply to me (see below).
 Since the source has now been extensively commented (in German!) and a 
 number of library functions have been included directly so that it can be 
 compiled on its own, it has grown to a stately 46 kB in the meantime. 
 However the portion needed only for TOS2GEM support is relatively small 
 (not including the comments), so don't be frightened...


 6. Where is the programmers documentation?
 ------------------------------------------
 It's still not quite complete at the moment. I have decided to release 
 the hypertext with information (not only) for programmers in its still 
 incomplete form, since it has now become at least half-way usable. 
 To view it you need ST-Guide by Holger Weets, who I wish to thank once 
 more here for this wonderful tool.

 In addition, those who understand German will find articles in 
 ST-Computer magazine for 04/95 and 05/95 very helpful. Furthermore it is 
 suggested that all programmers should take a look at the TOS2GEM library 
 from Dirk Klemmt (klemmt@stud.uni-frankfurt.de) for Pure and Gnu C, 
 since this makes the use of TOS2GEM childishly easy. A short overview of 
 its capabilities can be obtained from ST-Computer 05/95. Those wanting to 
 know more should approach Dirk, since I have had little or nothing to do 
 with the library itself.
 

 7. INSPECT.TTP
 --------------
 This tiny program serves as an aid for programmers who want to write 
 applications with TOS2GEM support. You will find more about this in the 
 text and hypertext files.


 8. Disclaimer
 -------------
 Although TOS2GEM and the associated utilities have been carefully 
 programmed and thoroughly tested I cannot guarantee that no bugs remain. 
 Therefore I cannot guarantee either the fault-free operation of TOS2GEM, 
 nor its fitness for any particular purpose. You use TOS2GEM at your own 
 risk!

 I, Thomas Binder, do not accept any liability or responsibility for any 
 direct or indirect damage that may arise, either financial, material or 
 any other kind, from either the use or misuse of TOS2GEM and its 
 associated applications, utilities and documentation.

 All trademarks mentioned in the TOS2GEM documentation are acknowledged 
 and recognised.


 9. Distribution of TOS2GEM
 --------------------------
 TOS2GEM is freeware and may be copied and used freely. However 
 distribution may take place only in one of two variants, where all the 
 named files have to be copied unchanged in each case (archiving is 
 permitted):

 a) Complete package
 Contains TOS2GEM.PRG, T2GRESET.PRG, T2G_INTR.PRG, TOS2GEM.H, TOS2GEM.TXT, 
 T2G_TEST.PRG, PRIME_NO.TOS, INSPECT.TTP, TOS2GEM.HYP and TOS2GEM.REF. 
 This package is mainly intended for distributing TOS2GEM on its own (when 
 it is not included with another program).

b) Mini-package
 Contains only TOS2GEM.PRG, T2GRESET.PRG, T2G_INTR.PRG and TOS2GEM.TXT. 
 This variant should only be used when one wants TOS2GEM to accompany a 
 program that requires it.

 Those who have developed their own programs that need or support TOS2GEM 
 may include TOS2GEM in their program package (in one of the  above-
 mentioned forms) under the following conditions:

   - TOS2GEM must be copied to its own folder
   - The documentation or the program must contain instructions for 
     using TOS2GEM
   - It must be clear from the documentation that TOS2GEM is a separate, 
     free-standing utility developed by me, and that it does not belong 
     to the actual program.

 Furthermore I would be most grateful if you would send me a sample of the 
 program.


 10. Contact with the author
 ---------------------------
 For those who have found errors, would like the test program source code, 
 need help with programming TOS2GEM applications, want to express praise, 
 criticism or simply to chat, here are my details:

 Thomas Binder
 Johann-Valentin-May-Strasse 7
 64665 Alsbach-Haehnlein
 Germany

 InterNet: binder@rbg.informatik.th-darmstadt.de
 IRC: Gryf

 Please include a disk and SAE (Self Addressed Envelope) along with either 
 an International Reply Coupon or a second disk, or be in a position to 
 receive binaries via E-mail. You should also state whether you want the 
 old or new source for T2G_BSP.TOS (renamed T2G_TEST.TOS in English). In 
 the new version a somewhat more complicated, but multi-tasking friendly 
 method is used for control, whereas the older version proceeds 
 'conventionally'. The new version is recommended only for those that 
 already have some experience with TOS2GEM! For beginners I recommend the 
 older source code.

 TOS2GEM has taken a considerable amount of my free time to develop and 
 if you'd like to contribute to ensure I continue to support the Atari 
 platform please don't hesitate to do so! This is aimed particularly, but 
 not exclusively, at those that want to support TOS2GEM in their own 
 programs.

 My banking arrangements are:
 Dresdner Bank AG Frankfurt am Main
 Account No: 9 024 050 00
 Sort code: 500 800 00

 Thanks a lot!


 11.British support
 -------------------
 British support for the English-language version of TOS2GEM  is provided 
 by Denesh Bhabuta at:

   CyberSTrider
   203 Parr Lane
   Unsworth
   Bury
   Lancashire
   BL9 8JW
   
 He will be pleased to accept any contributions on behalf of the  TOS2GEM 
 author gratefully,  sent by Sterling or Euro-cheque, International Money 
 Order or Postal Order; a minimum of 6 is recommended.

 Denesh also supports other Freeware and Shareware,  much of it of recent 
 German origin. He may be contacted by E-mail at:

   dbhabuta@cix.compulink.co.uk      or
   danny@micros.hensa.ac.uk


 12. What programs support TOS2GEM?
 ---------------------------------
 Currently three main programs use TOS2GEM as Console windows:
 - POVSHELL v1.3 onwards, programmed by Dirk Klemmt:
   Email: klemmt@stud.uni-frankfurt.de
 - Thing alternative desktop, programmed by Arno Welzel:
   Email: aw@zaphot.augusta.de
 - The shell Easy-PGP by Manfred Ssykor:
   Email: msy@lafp.tng.oche.de

 Other programmers are interested but until I'm 100% certain we'll leave 
 it at that.

 At this time I would like to repeat an open call to all who have 
 previously shown an interest: Let's hear from you! I would be glad of 
 some more feedback so that I know whether and what things you are 
 programming with TOS2GEM.


 13. Credits and thanks
 ----------------------
 The following people either directly or indirectly took part in the 
 development of TOS2GEM (in alphabetical order):
 - Alexander Clauss
 - Joe Connor
 - Frank Danapfel
 - Dirk Klemmt
 - Harald Schnfeld
 - Thomas Schulze
 - Manfrd Ssykor
 - Arno Welzel

 In addition I would like to thank all those who have been willing to send 
 me a contribution for TOS2GEM.


 14. Outloook for further development of TOS2GEM
 -----------------------------------------------
 Up to now there have been problems when one uses TOS2GEM and Gemini 
 together (not fundamentally, but in certain situations - see hypertext). 
 To overcome this will be the next step.

 Oh yes, sometime I should also finish writing the docs....


 15. History
 -----------
 This history only contains the changes since the last pre-release 
 beta-version of TOS2GEM, since otherwise it would be a bit long...
 
 TOS2GEM dated 26.07.1995:
    - Stupidly the MiNT cookie was only interrogated when starting  
      TOS2GEM, therefore TOS2GEM also used buffering under MiNT if it 
      was started first (the recognition of input calls doesn't work with 
      MiNT, therefore one must not buffer).
    - The TOS2GEM test program now uses the option to reserve TOS2GEM 
      really only when required. One can therefore start it repeatedly  
      (with multi-tasking), as TOS2GEM is not permanently engaged.

    TOS2GEM-beta dated 09.07.1995:
    - A number of errors and inadequacies with the 'stats' evaluation 
      removed.
    - With time-controlled buffering TOS2GEM now uses the VBL-interrupt, 
      to trigger a screen refresh even when there has been no TOS-output 
      for some time (previously checks for exceeding the set period were 
      only made during output).
    - New file 'T2G_INTR.PRG' that switches on and off the use of the 
      interrupt in cases when problems arise.
    - With buffering active TOS2GEM now also empties the buffer when the 
      visible area is moved.

    TOS2GEM dated 21.06.1995:
    - New 'stats' Cookie-element, in which the contents of several 
      internal variables are stored when output redirection is not 
      activated so that they can be read out later (more about this in the 
      docs).

    TOS2GEM-beta dated 01.06.1995:
    - During initialisation of the text buffer, setting of null-bytes for 
      line-ends was left out (the source line seems to have got lost when 
      colour support was added...)

    TOS2GEM-beta dated 11.05.1995
    - Serious error under MiNT removed: Due to carelessness in the source,
      buffering also took place under MiNT, though input recognition does 
      not work in that case.
    - TOS2GEM can now also use time-controlled output buffering; with 
      this, screen refreshes take place at pre-set time intervals. This is 
      achieved by negative values in the 'buffer_output' Cookie-element.
    - Line redraw in colour mode has been converted to a 'flicker-free' 
      method, which, though a little slower, is kinder on the eyes.

    TOS2GEM-beta dated 07.04.1995
    - TOS2GEM can now also handle colour sequences (in which I also 
      include those for inverted video)!  The new 'color' Cookie-element 
      determines the type of colour support (compatible or VDI- 
      conforming). More about this in the HYP doc, which has now been 
      released.
    - Under SingleTOS, TOS2GEM output buffering now also uses a timer 
      triggering a refresh after 500 ms for Bconstat calls. Thanks to 
      this, TOS programs that interrogate the keyboard via Bconstat/Bconin 
      will work correctly (e.g. SYSOK). Under MagiC this is unnecessary, 
      as there the buffer will be cleared at each Bconstat call anyway.

    TOS2GEM dated 24.03.1995
    - Since I was informed in a bug report that the TOS2GEM Cookie was 
      still present after a reset, TOS2GEM now also hooks into the reset 
      vector to clear the Cookie pointer even when it only has to extend 
      the Cookie-jar. I hope that this has removed the problem (I couldn't 
      reproduce it).
    - With output buffering active, a refresh is now also performed when 
      the screen contents have (internally) moved by the window height. 
      Thanks to this, no output will get lost completely.

    TOS2GEM-beta dated 02.02.1995
    - Keyboard input is recognised now also under MagiC, so that buffering 
      is also possible with this operating system. Unfortunately it 
      doesn't work with MiNT/MultiTOS (though here one is likely to forego 
      TOS2GEM in favour of TOSWIN/MINIWIN, which natutally also applies to 
      VT52 under MagiC). 
    - Buffering could be improved once more, so that output is more than  
      twice as fast as without buffering (this is in part faster than the 
      standard GEMDOS/BIOS output).

    TOS2GEM-beta dated 31.01.1995(?)
    - With the new 'buffer_output' Cookie element one can achieve 
      buffering of the output, which results in a marked increase in 
      speed. Unfortunately this only works under SingleTOS, as only there 
      can TOS2GEM recognise keyboard output correctly (it is necessary to 
      clear the buffer in this case, so one can recogise what should be 
      input).

    TOS2GEM dated 19.01.1995
    - If TOS2GEM had to create or extend the Cookie-jar, this was lost 
      when output redirection was first activated as it lay in the same 
      memory region as the VDI array.

    TOS2GEM dated 03.01.1995
    - In re-activating output redirection via 'switch_output', the 
      Y-offset was not adapted correctly. Since this was not an 
      insignificant error, it is advisable to use at least this version 
      (note the 'date' Cookie-element!) in programs in which the size of 
      the TOS2GEM window can be altered.
    - TOS2GEM.PRG now has the memory protection flag 'global' once again 
      (I forgot it the last time, because the Pure C linker unfortunately 
      can't do this (at least that of PC 1.0)).
    - The header file has been improved: The constant RESERVED_SIZE now 
      exists for the reserved field of the Cookie, specifying the size of 
      this field.

    TOS2GEM dated 12.12.1994:
    - A small error occurred during calculation of two internal variables 
      that resulted in faulty scrolling in some circumstances (if only 
      the first pixel row of a line was visible).
    - TOS2GEM test example included in the 'large' archive, so that one 
      can see what the purpose of TOS2GEM is and how it works. I hadn't 
      thought of this at first (thanks to Dirk Klemmt, who brought this 
      omission to my attention).

    TOS2GEM dated 22.11.1994:
    - First official version, unfortunately without ST-Guide documentation 
      (I wanted to release TOS2GEM at the proTOS...)
    - A problem under MagiC that switches on the 'real' cursor for an 
      'Fread' call for the console and completely misplaces the one for 
      TOS2GEM has now been circumvented. Though the solution was not a 
      'clean' one (write access to the negative LineA variables), I could 
      not find any other reliable method.
    - TOS2GEM now has a 'Global' memory protection flag, so that no 
      problems arise in this respect with Mint/MultiTOS.


 15. English translation
 -----------------------
 English version of this document by Joe Connor, with additions and 
 corrections in various files by Peter West (who is also responsible for 
 the hypertext translation).
