    Short information for TOS2GEM of 13.09.1996. As at: 13.09.1996
    --------------------------------------------------------------

    1. What is TOS2GEM?
    -------------------

    TOS2GEM is a program for the AUTO-folder which offers GEM applications 
    a flexible way to redirect screen output of .TOS or .TTP programs to 
    a window. This is achieved with VDI text commands, and allows 
    programmers of shells or alternative desktops to install a kind of 
    Console window without much effort.

    From this it becomes clear, of course, that TOS2GEM is intended for 
    use mainly under SingleTOS. Actually it will also run under Geneva, 
    MagiC and MultiTOS, though here its use is of course very restricted 
    as TOS programs under these systems run in windows anyway (if they 
    are started correctly).

    The most important properties of TOS2GEM at a glance:
    - Offers programmers a clean way of diverting output of TOS programs 
      started after it to a GEM window
    - Simulates TOS screens of any desired size (so not just the boring 
      80x25), that may also be only partly visible
    - Works with all non-proportional fonts in any point size
    - With (optional) output buffering can have faster output than with 
      GEMDOS/BIOS (only for SingleTOS/MagiC)
    - Optionally offers a 'history' buffer for older output ('scroll-back')
    - Has complete VT52 emulation (colour sequences only optional)


    2. How does one install it?
    ---------------------------

    TOS2GEM.PRG is simply copied to the AUTO-folder on the boot partition 
    and during each boot process creates a cookie which the programmer 
    can use to control the use of TOS2GEM. But if required TOS2GEM.PRG 
    can also be started from ther desktop.


    3. What is T2GRESET.PRG?
    -------------------------

    Programs have to reserve TOS2GEM for themselves; until it is released 
    other programs cannot make use of TOS2GEM. Should a program that has 
    reserved TOS2GEM for itself crash, or forget to release it when it 
    terminates, then this blockage can be removed by calling T2GRESET. 
    It is not advisable to call T2GRESET while the application that 
    reserved TOS2GEM is still running, because this will necessarily lead 
    to serious complications. An indication that such a blockage has 
    occurred is when no program using TOS2GEM is running and a newly 
    started one reports that it cannot reserve it for itself.


    4. What is T2G_INTR.PRG?
    ------------------------

    Since the beta version of 09.07.1995 TOS2GEM hooks into the VBL 
    (vertical blanking) interrupt in order to be able to trigger a 
    refresh of the screen contents during time-controlled buffering even 
    when the running program has made no output for some time (previously 
    checks were made directly during output only to see whether the time 
    interval had been exceeded). If this should give rise to unexpected 
    problems (e.g. unexplained crashes while output redirection is 
    active) one can use T2G_INTR.PRG to switch off the use of the 
    interrupt (and switch it back on again if required). If this is 
    desired or required permanently, then T2G_INTR.PRG should be placed 
    physically after TOS2GEM.PRG in the AUTO folder.

    Important: Those who have included the mini-package of TOS2GEM with 
    their own programs in the past (see item 9) should ensure that 
    T2G_INTR.PRG is included in this pckage!


    5. What are T2G_BSP.PRG/T2G_TEST.PRG and PRIMZAHL.TOS/PRIME_NO.TOS?
    -------------------------------------------------------------------

    As it is difficult to visualise what TOS2GEM actually does from a
    theoretical description of how it works, I have written a small 
    example program (called T2G_BSP.PRG for 'TOS2GEM-Beispiel' (-example)
    in German and T2G_TEST.PRG in the English translation). Incidentally, 
    neither file is contained in the small archive (see item 9) such as 
    the one included with Thing!

    After starting this program (TOS2GEM must of course have been started 
    earlier) a dialog box appears in which one can specify the dimensions 
    of the TOS screen to be simulated by TOS2GEM, and the maximum amount 
    of this to be visible. In addition one can select here whether and how 
    output buffering and colour support are to be used by TOS2GEM. 

    Following this a corresponding window will be opened to which (already 
    using TOS2GEM redirection) the dimensions to be realised are written. 
    Directly after this the program PRIMZAHL.TOS (PRIME_NO.TOS in English) 
    will be started (it has to be present in the same directory) which 
    can calculate all the primes up to a specified number which the user 
    is asked to input, using the 'Sieve of Eratosthenes' algorithm; one 
    could also use any other .TOS program as long as it is placed in the 
    correct directory and renamed to PRIMZAHL.TOS or PRIME_NO.TOS for the 
    German and English versions of the example program respectively.

    At the end of the prime number program one can position the window 
    into which clean output was made anywhere on the screen. Clicking on 
    the 'Closer' button terminates the program, a click within the working 
    area of the window brings up an alert offering three choices: 'Resize' 
    permits altering the TOS2GEM window size (with the same dialog as at 
    its start; the screen is cleared if the total size is altered). With 
    'Rerun' PRIMZAHL/PRIME_NO.TOS can be started again and 'Nothing' does 
    just that...

    The example program has been kept simple deliberately, so that one 
    can see that TOS2GEM support is relatively easy. Not all capabilities 
    of TOS2GEM are demonstrated (in particular neither various fonts and 
    character sizes nor a 'scroll-back' history buffer are available), 
    but it should make clear the possibilities that TOS2GEM offers.

    Those who would like to obtain the source code in order to obtain a 
    concrete picture of TOS2GEM support should get in touch with me (see 
    below). As the source has been extensively furnished with comments 
    (in German) and some library fuinctions have been incorporated 
    directly so that it can be compiled as it stands, its size has grown 
    to some 46 kilobytes. However the portion that is required for TOS2GEM 
    support only is relatively small (excluding the comments), so there's 
    no need to be afraid...


    6. Docs for programmers
    -----------------------

    I have decided to release the hypertext with information (not only) 
    for programmers in its still incomplete version, since it may be 
    half-way usable in its present state. To view it one requires ST-GUIDE 
    by Holger Weets, whom I'd like to thank here once more for this 
    excellent utility.

    In addition to the hypertext docs, those who can read German may be 
    helped by a look at 'ST-Computer' 04/95 and 05/95.

    In addition I'd advise everyone to take a look at the TOS2GEM library 
    by Dirk Klemmt (klemmt@stud.uni-frankfurt.de) for Pure and Gnu C, 
    which makes using TOS2GEM child's play. A short summary of its 
    capabilities can be obtained from 'ST-Computer' 05/95. Anyone wishing 
    to know more please get in touch directly with Dirk, as I have little 
    or nothing to do with the library itself.


    7. INSPECT.TTP
    --------------

    This tiny program serves as an aid for programmers who wish to write 
    applications with TOS2GEM support. More about this can be found in the 
    hypertext.


    8. Legal
    --------

    TOS2GEM was programmed with great care and tested extensively. 
    However one cannot exclude the possibility that some bugs remain. I 
    can therefore neither guarantee fault-free operation of TOS2GEM nor 
    its fitness for any particular purpose.

    Furthermore, 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.

    The same applies, of course, to the associated applications, utilities 
    and documentation contained in the archive.


    9. Distribution of TOS2GEM
    --------------------------

    TOS2GEM is freeware and may be copied and used freely. For general  
    distribution one of two of the following packages has to be chosen,  
    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_BSP/T2G_TEST.PRG, PRIMZAHL/PRIME_NO.TOS, INSPECT.TTP, 
    as well as 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 support or require 
    TOS2GEM may include TOS2GEM in their program package (in one of the 
    forms mentioned above) no matter whether it is PD/Shareware or 
    commercial software, as long as the following conditions are fulfilled:

    - 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

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


    10. Contact with the Author
    ---------------------------

    Anyone who has found any bugs, would like the source code, needs help 
    for programming TOS2GEM applications, wishes to send praise, criticism 
    and/or suggestions or just simply wishes to 'chat' with me can make 
    use of the following addresses:

    Thomas Binder
    Johann-Valentin-May-Straže 7
    64665 Alsbach-H„hnlein
    Deutschland/Germany

    InterNet: binder@rbg.informatik.tu-darmstadt.de (preferred)
              gryf@hrzpub.tu-darmstadt.de
    MausNet: Thomas_Binder @ HD (no mails > 16K!)
    IRC: Gryf

    Those who would like to obtain the extensively commented source code 
    for the TOS2GEM example should either send me a self-addressed 
    envelope with German stamps or 2 International Reply Coupons, or be 
    in a position to receive binaries by Email. In addition you should 
    specify whether you want the code for the old or new TOS2GEM example. 
    The newer one uses a little more complicated but in return 
    multitasking-friendly method of control, while the old version 
    proceeds 'conventionally'. I'd only recommend the new version to 
    those who have had previous experience with TOS2GEM programming! For 
    beginners I suggest the older source code.

    Naturally I'd be very happy if some of you would reward the work  
    that I have put into TOS2GEM with a small contribution sent to my bank 
    account (or to my British representative - see SUPPORT.TXT.) Every 
    contributions safeguards further development of TOS2GEM, which I hope 
    is desirable.

    My banking details:
    Dresdner Bank AG Frankfurt am Main
    Konto-Nummer/Account No.00
    Bankleitzahl/Sort code: 500 800 00

    Many thanks!


    11. Which programs support TOS2GEM?
    -----------------------------------

    Up to now I am aware of four programs that use TOS2GEM to redirect 
    output of TOS programs into a window:

    - The POVShell by Dirk Klemmt (klemmt@stud.uni-frankfurt.de) from 
      Version 1.3 onwards
    - The alternative desktop Thing originally programmed by Arno Welzel 
      (arno@alphasystems.de) and now with continued development by me
    - The Shell Easy-PGP by Manfred Ssykor (msy@lafp.tng.oche.de)
    - A POV-3.0 port by Szymon Stasik (ss158962@students.mimuw.edu.pl)

    Since in the age of MagiC and N.AES no other people seem to be 
    interested in supporting TOS2GEM in their own programs, I have not 
    done much more in the docs for programmers. I don't want to do 
    unnecessary work ;)

    12. Thanks
    ----------

    The following people took part in the development of TOS2GEM, directly 
    or indirectly (in alphabetical order):

    - Denesh Bhabuta
    - Alexander Clauss
    - Joe Connor
    - Frank Danapfel
    - Dirk Klemmt
    - Harald Sch”nfeld
    - Thomas Schulze
    - Manfred Ssykor
    - Arno Welzel

    In addition I'd like to thank all those who have sent me a 
    contribution for TOS2GEM.


    13. Outlook for further development of TOS2GEM
    ----------------------------------------------

    Apart from some possible bug fixes I doubt if I'll do much more with 
    TOS2GEM, since in my opinion it's already relatively mature; in any 
    case there seems to be no great demand for it from programmers or 
    users any more.


    14. History
    -----------

    The history only contains changes from the last pre-release 
    beta-version of TOS2GEM, as it would get a bit long otherwise...

    TOS2GEM of 13.09.1996:
    - No more crashes if the visible portion lies outside the physical 
      screen (even though this is not allowed anyway according to the docs)
    - Under certain circumstances the internal colour-buffer pointer 
      introduced in the beta of 10.02.1996 was not updated when diversion 
      was switched back on again, which resulted in the colour buffer 
      being kept at the wrong position

    TOS2GEM-beta of 01.03.1996:
    - Further small increase in output speed with buffering active

    TOS2GEM-beta of 10.02.1996:
    - If the time interval for time- and(!) interrupt-controlled buffering 
      is smaller than 200ms, TOS2GEM omits refreshes during input as one 
      happens often enough. Thanks to this output from Mupfel under MagiC 
      is no longer painfully slow (Mupfel asks after outputting each(!) 
      character whether a character is on the way, which TOS2GEM under 
      MagiC must normally evaluate as a refresh request)
    - The output speed in colour mode is now almost as fast with a white 
      background as in monochrome, since in this case the additional 
      drawing of the character background is dispensed with in favour of 
      the replace-mode. Since a white background is the norm, this 
      improvement is very noticeable
    - Output buffering too has now become appreciably more efficient when
      lines contain many space charactes at the ends. Although this is 
      not quite as common as a white background, it still happens often 
      enough to make an appreciable difference

    TOS2GEM of 26.07.1995:
    - Stupidly the 'MiNT' cookie was only looked for when TOS2GEM was 
      started, so that TOS2GEM also buffered under MiNT when this was 
      started first (recognition of input requests doesn't work with MiNT 
      so one may not buffer with it)
    - The TOS2GEM example program now exploits the possibility of 
      reserving TOS2GEM really only when it is needed. So one can now 
      start it several times (with multitasking) as TOS2GEM is not 
      permanently engaged

    TOS2GEM-beta of 09.07.1995:
    - A number of errors or inadequacies in the stats-evaluation removed
    - With time-controlled buffering TOS2GEM hooks into the VBL (vertical 
      blanking) interrupt in order to be able to trigger a refresh of the 
      screen contents even when the running program has made no output for 
      some time (previously checks were made directly during output only 
      to see whether the time interval had been exceeded)
    - New file 'T2G_INTR.PRG' to switch interrupt usage on and off, in 
      case of problems arising
    - With active buffering TOS2GEM now also clears the buffer when the 
      visible area is moved

    TOS2GEM of 21.06.1995:
    - New cookie-element 'stats', in which the contents of several 
      internal variables can be stored when output redirection is 
      inactive, to be read out again later (see more about this in the 
      docs)

    TOS2GEM-beta of 01.06.1995:
    - During initialising of the text buffers setting Null bytes for the 
      line end was omitted (the source line seems to have got lost while 
      incorporating colour support...)

    TOS2GEM-beta of 11.05.1995
    - Serious error under MiNT removed: Due to an oversight in the source, 
      buffering took place under MiNT though the recognition of input 
      does not work there
    - TOS2GEM can now also use time-controlled output buffering, where 
      refreshes take place at specified time intervals. This is achieved 
      by negative values in the cookie element 'buffer_output'
    - The line redraw in colour mode was altered to a 'flicker-free' 
      method, which while being slower is far easier on the eye

    TOS2GEM-beta of 07.04.1995
    - TOS2GEM now also uses the colour sequences (which also includes 
      inversion!). The new cookie element 'color' sets the type of colour 
      support (compatible or VDI-conforming). More about this in the .HYP 
      docs, which have now been released
    - Under SingleTOS, TOS2GEM now also uses a timer that triggers a 
      refresh after 500 ms at Bconstat calls during output buffering. This 
      permits TOS programs that interrogate the keyboard with Bconstat/ 
      Bconin to work correctly (e.g. SYSOK). Under MagiC this is not 
      necessary as in that case the buffer is cleared anyway at each 
      Bconstat call

    TOS2GEM of 24.03.1995
    - As a bug report informed me that the 'TOS2GEM' cookie was still 
      present after a reset, TOS2GEM no also hooks into the reset vector 
      to clear the cookie pointer even when it only needs to extend the 
      cookie jar. I hope this has removed the problem (I could not 
      duplicate it)
    - With output buffering active, a 'refresh' will also be executed now 
      when the screen contents (internally) have moved by the height of 
      the window. This prevents any output from being completely 
      'swallowed'

    TOS2GEM-beta of 02.02.1995
    - Now the recognition of keyboard input also works under MagiC, so 
      that buffering is also possible with that operating system. 
      Unfortunately it does not work with MiNT/MultiTOS (but there one 
      would use TOSWIN/MINIWIN in preference to TOS2GEM anyway, which also 
      applies to VT52 under MagiC, of course
    - Buffering could be improved once more so that output now takes place 
      more than twice as fast as without buffering (in part this is faster 
      than the standard GEMDOS/BIOS output)

    TOS2GEM-beta of 31.01.1995(?)
    - With the new cookie element 'buffer_output' one can achieve 
      buffering of the output, which brings a marked speed increase. 
      Unfortunately this only works with SingleTOS, as TOS2GEM can only 
      recognise keyboard input correctly there (in such a case the buffer 
      has to be cleared to make it possible to see what is to be input)

    TOS2GEM of 19.01.1995
    - If TOS2GEM had to create or extend the cookie jar, this was lost at 
      the first activation of output redirection, as it lay in the same 
      memory region as the VDI array

    TOS2GEM of 03.01.1995
    - When reactivating output redirection with 'switch_output' the 
      y_offset was not adapted correctly. As this is a not inconsiderable 
      error, it is advisable to use at least this TOS2GEM version with 
      programs in which the size of the TOS2GEM window can be altered 
      (take note of the 'date' cookie element!)
    - TOS2GEM.PRG now has the memory protection flag 'Global' once again 
      (I had forgotten this the last time because the Pure C linker 
      unfortunately cannot do this (at least not the one from 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 the field

    TOS2GEM of 12.12.1994:
    - A small error crept into the calculation of two internal variables 
      which led to faulty scrolling in certain circumstances (if only the 
      first row of pixels of a line was visible)
    - TOS2GEM example included into the 'large' archive so that one can 
      visualise what TOS2GEM actually does and how it works. I hadn't 
      thought of this originally (thanks to Dirk Klemmt, who pointed this 
      out to me)

    TOS2GEM of 22.11.1994:
    - First official version, unfortunately still without ST-Guide docs 
      (I wanted to 'release' TOS2GEM at the proTOS...)
    - Under MagiC there is a workaround for the problem that an 'Fread' 
      call for the Console switches on the 'real' cursor and places the 
      one for TOS2GEM in completely the wrong place. The solution is a 
      little 'dirty' (write access to the negative LineA variables) but I 
      could find no other reliable method to accomplish this
    - TOS2GEM now has the memory protection flag 'Global', so that no 
      problems should arise with this under MiNT/MultiTOS

-------------------------------------------------------------------------
English translation of this and associated files: Peter West, TransAction.
