    Kurzinformationen zu TOS2GEM vom 21.06.1995, Stand: 21.06.1995
    --------------------------------------------------------------

    (An English version of this text will be available soon!)


    1. Was ist TOS2GEM?
    -------------------

    TOS2GEM ist ein Programm fr den AUTO-Ordner, das es GEM-Applikationen 
    auf flexible Weise ermglicht, die Ausgaben von .TOS bzw. .TTP-
    Programmen in ein Fenster umzulenken, was durch Benutzung von VDI-
    Textbefehlen erreicht wird. Somit knnen Programmierer von Shells oder 
    alternativen Desktops ohne groen Aufwand eine Art Console-Fenster 
    einrichten.

    Dadurch ergibt sich natrlich, da TOS2GEM hauptschlich fr den 
    Einsatz unter SingleTOS gedacht ist. Allerdings luft es auch unter 
    Geneva, MagiC und MultiTOS, wobei hier natrlich der Nutzen sehr 
    eingeschrnkt ist, da die TOS-Programme unter diesen Systemen sowieso 
    in Fenstern laufen (wenn sie richtig gestartet werden).

    Die wichtigsten Eigenschaften von TOS2GEM auf einen Blick:
    - bietet saubere Mglichkeit fr Programmierer, Ausgaben von 
      nachgestarteten TOS-Programmen in ein GEM-Fenster zu lenken
    - simuliert TOS-Bildschirme beliebiger Gre (also nicht nur 
      langweilige 80x25), die auch nur teilweise sichtbar sein drfen
    - arbeitet mit allen nicht-proportionalen Zeichenstzen in beliebiger 
      Gre zusammen
    - mit (optionaler) Ausgabepufferung teilweise schnellere Ausgabe als 
      mit GEMDOS/BIOS (nur fr SingleTOS/MagiC)
    - bietet auf Wunsch einen Puffer fr ltere Ausgaben ("Scrollback")
    - hat vollstndige VT52-Emulation (Farbsequenzen nur optional)


    2. Wie wird's installiert?
    --------------------------

    TOS2GEM.PRG wird einfach in den AUTO-Ordner der Bootpartition kopiert 
    und richtet dann bei jedem Booten einen Cookie ein, ber den 
    Programmierer die Benutzung von TOS2GEM steuern knnen. Bei Bedarf kann 
    TOS2GEM.PRG aber auch vom Desktop gestartet werden.


    3. Was ist T2GRESET.PRG?
    -------------------------

    Programme mssen TOS2GEM fr sich reservieren; bis zur Freigabe knnen 
    andere Programme die Dienste von TOS2GEM nicht in Anspruch nehmen. 
    Sollte nun ein Programm, das TOS2GEM fr sich reserviert hatte, 
    abstrzen oder am Ende die Freigabe vergessen, kann durch Aufruf von 
    T2GRESET diese Blockade aufgehoben werden. Es ist nicht sehr ratsam, 
    T2GRESET aufzurufen, wenn die Applikation, die TOS2GEM reserviert hat, 
    noch luft, da es dann zwangslufig zu schweren Komplikationen kommt. 
    Kennzeichen fr eine vorliegende Blockade ist, wenn kein Programm 
    luft, das TOS2GEM benutzt und ein neu gestartetes meldet, es knne die 
    Reservierung nicht vornehmen.


    4. Was sind T2G_BSP.PRG und PRIMZAHL.TOS?
    -----------------------------------------

    Da sich anhand der theoretischen Beschreibung der Funktionsweise von 
    TOS2GEM wohl niemand genau ein Bild davon machen kann, was TOS2GEM 
    eigentlich macht, habe ich ein kleines Beispielprogramm geschrieben 
    (eben T2G_BSP.PRG oder ausgeschrieben TOS2GEM-Beispiel). Die beiden 
    Dateien sind im kleinen Archiv (siehe Punkt 8) brigens nicht enthalten!

    Nach dem Start des Programms (TOS2GEM mu natrlich vorher gestartet 
    worden sein) erscheint eine Dialogbox, in der man die Ausmae des von 
    TOS2GEM zu simulierenden TOS-Bildschirms angibt und wieviel davon 
    maximal sichtbar sein soll. Auerdem kann hier gewhlt werden, ob und 
    wie die Ausgabepufferung und die Farbuntersttzung von TOS2GEM benutzt 
    werden sollen. Im Anschlu wird ein entsprechendes Fenster geffnet, in 
    das (bereits per TOS2GEM-Umlenkung) die realisierten Ausmae 
    geschrieben werden. Direkt danach wird das Programm PRIMZAHL.TOS (das 
    sich daher im gleichen Verzeichnis befinden mu) gestartet, das eine 
    simple Primzahlberechnung mit dem "Sieb des Eratosthenes" realisiert 
    (man kann auch jedes andere TOS-Programm nehmen, es mu nur als 
    PRIMZAHL.TOS im richtigen Verzeichnis stehen). Nach Ende des 
    Primzahlprogramms kann man das Fenster, in das die Ausgaben ja sauber 
    umgelenkt wurden, nach Lust und Laune auf dem Bildschirm plazieren. Ein 
    Druck auf den Closer beendet das Programm, nach einem Klick in den 
    Arbeitsbereich des Fensters erscheint eine Alertbox mit drei 
    Wahlmglichkeiten: "Resize" erlaubt eine nderung der TOS2GEM-
    Bildschirmgre (mit dem gleichen Dialog wie zu Beginn; dabei wird der 
    Bildschirm gelscht, wenn seine Gesamtgre verndert wird). Mit 
    "Rerun" kann nochmal PRIMZAHL.TOS gestartet werden und "Nichts" macht 
    genau dies...

    Das Beispielprogramm ist bewut einfach gehalten, u.a. damit man sieht, 
    da eine TOS2GEM-Untersttzung relativ einfach mglich ist. Es werden 
    nicht alle Mglichkeiten von TOS2GEM demonstriert (insbesondere werden 
    weder verschiedene Zeichenstze in unterschiedlichen Gren benutzt 
    noch ein "Scrollback" geboten), allerdings sollte es trotzdem gut 
    verdeutlichen, welche Mglichkeiten TOS2GEM bietet. Wer den Quellcode 
    haben mchte, um sich mal ein konkretes Bild von der TOS2GEM-
    Untersttzung machen zu knnen, soll sich bitte melden (siehe unten). 
    Da der Source inzwischen ausfhrlich kommentiert wurde und einige 
    Libraryfunktionen direkt eingebunden wurden, damit er eigenstndig 
    compiliert werden kann, ist seine Gre inzwischen auf stattliche 40 
    Kilobyte angewachsen. Allerdings ist dabei der Anteil dessen, was nur 
    fr die TOS2GEM-Untersttzung ntig ist, relativ gering (die Kommentare 
    nicht mitgerechnet), also nicht erschrecken...


    5. Die Doku fr Programmierer
    -----------------------------

    Ich habe mich entschlossen, den Hypertext mit Informationen (nicht nur) 
    fr Programmierer in seiner immer noch unvollstndigen Fassung 
    freizugeben, da er inzwischen halbwegs brauchbar sein drfte. Zum 
    Anschauen bentigt man den ST-Guide von Holger Weets, dem ich an dieser 
    Stelle nochmal ganz herzlich fr diese groartige Tool danken mchte.

    Zustzlich zur Hypertext-Doku kann auch ein Blick in die ST-Computer 04/
    95 und 05/95 sicher hilfreich sein.

    Darberhinaus sei jedem angeraten, sich einmal die TOS2GEM-Library von 
    Dirk Klemmt (klemmt@informatik.uni-frankfurt.de) fr Pure und Gnu C 
    anzusehen, da sie die Benutzung von TOS2GEM zum Kinderspiel macht. 
    Einen kurzen berblick ber ihre Fhigkeiten kann man in der ST-
    Computer 05/95 erhalten. Wer mehr wissen will, wendet sich bitte direkt 
    an Dirk, da ich mit der Library selbst wenig bis nichts zu tun habe.


    6. INSPECT.TTP
    --------------

    Dieses kleine Progrmmchen dient als Hilfe fr Programmierer, die 
    Applikationen mit TOS2GEM-Untersttzung schreiben wollen. Nheres dazu 
    findet sich im Hypertext.


    7. Rechtliches
    --------------

    TOS2GEM wurde mit groer Sorgfalt programmiert und eingehend getestet. 
    Es ist jedoch nicht auszuschlieen, da es noch Fehler enthlt. Ich 
    kann daher weder fr die einwandfreie Funktionsfhigkeit von TOS2GEM, 
    noch fr dessen Tauglichkeit fr einen bestimmten Zweck garantieren.

    Desweiteren erfolgt die Benutzung von TOS2GEM auf eigene Gefahr! Ich 
    bernehme keinerlei Haftung fr Schden, die direkt oder indirekt aus 
    der sach- oder unsachgemen Anwendung von TOS2GEM resultieren.

    Gleiches gilt selbstverstndlich auch fr die anderen im Archiv 
    enthaltenen Programme.


    8. Zum Kopieren von TOS2GEM
    ---------------------------

    TOS2GEM ist frei kopier- und benutzbar. Allerdings darf die Weitergabe 
    nur in folgenden zwei Varianten erfolgen, wobei jeweils alle 
    angegebenen Dateien unverndert kopiert werden mssen (Archivierung ist 
    erlaubt):

    a) Komplettpaket
    Enthlt TOS2GEM.PRG, T2GRESET.PRG, TOS2GEM.H, TOS2GEM.TXT, T2G_BSP.PRG, 
    PRIMZAHL.TOS, INSPECT.TTP sowie TOS2GEM.HYP und TOS2GEM.REF. Dieses 
    Paket ist hauptschlich fr die alleinige Weitergabe von TOS2GEM 
    gedacht (wenn es also nicht einem anderen Programm beigelegt ist).

    b) Minipaket
    Enthlt nur TOS2GEM.PRG, T2GRESET.PRG und TOS2GEM.TXT. Diese Variante 
    sollte nur dann gewhlt werden, wenn man TOS2GEM als Zugabe zu einem 
    Programm benutzen will, das es bentigt.

    Wer eigene Programme entwickelt hat, die TOS2GEM bentigen bzw. 
    untersttzen, darf TOS2GEM seinem Programmpaket beilegen (in einer der 
    beiden o.g. Formen), wenn er folgendes beachtet:

    - TOS2GEM mu in einen eigenen Ordner kopiert werden
    - In der Dokumentation oder im Programm mu ein Hinweis auf die 
      Benutzung von TOS2GEM erfolgen
    - In der Dokumentation mu deutlich erkennbar sein, da es sich bei 
      TOS2GEM um ein eigenstndiges, von mir entwickeltes Utility handelt, 
      das nicht zum eigentlichen Programm gehrt.

    Auerdem wre ich fr die Zusendung eines Exemplars des Programms sehr 
    dankbar.


    9. Kontakt mit dem Autor
    ------------------------

    Wer Fehler gefunden hat, den Beispiel-Source mchte, Hilfe bei der 
    Programmierung von TOS2GEM-Applikationen bentigt, Lob, Kritik und/oder 
    Vorschlge loswerden oder einfach nur mit mir "reden" mchte, kann sich 
    an folgende Adressen wenden:

    Thomas Binder
    Johann-Valentin-May-Strae 7
    64665 Alsbach-Hhnlein
    Deutschland

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

    Wer den ausfhrlich kommentierten Sourcecode zum TOS2GEM-Beispiel haben 
    will, sollte mir entweder einen adressierten und frankierten 
    Rckumschlag samt Diskette zusenden, oder in der Lage sein, Binaries 
    per EMail zu empfangen.

    Da TOS2GEM einen nicht unerheblich Teil meiner Freizeit beansprucht hat 
    und wohl auch weiter beanspruchen wird, bitte ich um Spenden, die mir 
    meine Arbeit honorieren und so gleichzeitig die Weiterentwicklung von 
    TOS2GEM sichern (dies richtet sich insbesondere, aber nicht 
    ausschlielich, an diejenigen, die TOS2GEM in eigenen Programmen 
    untersttzen wollen).

    Meine Bankverbindung lautet:
    Dresdner Bank AG Frankfurt am Main
    Konto-Nummer: 9 024 050 00
    Bankleitzahl: 500 800 00

    Vielen Dank!


    10. Welche Programme untersttzen TOS2GEM?
    ------------------------------------------

    Bislang gibt es drei Programme, die per TOS2GEM die Ausgaben von TOS-
    Programmen in ein Fenster umlenken:

    - Die POVShell von Dirk Klemmt (klemmt@informatik.uni-frankfurt.de) ab 
      Version 1.3
    - Der alternative Desktop Thing von Arno Welzel (aw@zaphot.augusta.de)
    - Die Shell Easy-PGP von Manfred Ssykor (msy@lafp.tng.oche.de)

    Auerdem haben sich bereits weitere Interessenten gemeldet, die ihre 
    Programme mit TOS2GEM-Untersttzung ausstatten wollen. Nheres kann ich 
    dazu aber erst sagen, wenn es 100%ig feststeht.

    Bei der Gelegenheit nochmal ein ffentlicher Aufruf an alle, die sich 
    bisher die Doku haben schicken lassen: Meldet Euch doch mal! Etwas mehr 
    Feedback wre mir sehr recht, damit ich wei, ob und wenn ja was fr 
    Sachen Ihr mit TOS2GEM-Untersttzung programmiert.


    11. Danksagungen
    ----------------

    Folgende Leute hatten, direkt oder indirekt, Anteil an der Entwicklung 
    von TOS2GEM (alphabetische Reihenfolge):

    - Alexander Clauss
    - Joe Conner
    - Frank Danapfel
    - Dirk Klemmt
    - Harald Schnfeld
    - Thomas Schulze
    - Manfred Ssykor
    - Arno Welzel


    12. Ausblick in die weitere Entwicklung von TOS2GEM
    ---------------------------------------------------

    Bislang gibt es Probleme, wenn man TOS2GEM und Gemini zusammen benutzt 
    (nicht grundstzlich, aber in bestimmten Situationen, siehe Hypertext). 
    Dies zu umgehen wird das nchste Ziel sein.

    Wenn ich danach nichts besseres zu tun habe, werde ich vielleicht 
    versuchen, TOS2GEM beizubringen, auch in teilweise verdeckten Bereichen 
    auszugeben. Allerdings habe ich bisher keine Idee, wie ich das Ganze 
    schnell *und* ohne kurze Phasen mit Zeichenfehlern machen soll.

    Ach ja, die Doku sollte ich vielleicht auch mal fertig schreiben...


    13. History
    -----------

    In der History sind nur die nderungen ab der letzten Pre-Release-Beta-
    Version von TOS2GEM enthalten, da es sonst etwas lnglich wrde...

    TOS2GEM vom 21.06.1995:
    - Neues Cookie-Element stats, in dem bei inaktiver Ausgabeumlenkung 
      die Inhalte einiger internen Variablen abgelegt werden, wo sie dann 
      spter wieder ausgelesen werden (mehr dazu in der Doku)

    TOS2GEM-Beta vom 01.06.1995:
    - Beim Initialisieren des Textpuffers wurde vergessen, die Nullbytes
      fr das Zeilenende zu setzen (die Sourcezeile ist wohl beim Einbau
      des Farbsupports verlorengegangen...)

    TOS2GEM-Beta vom 11.05.1995
    - Bsen Fehler unter MiNT entfernt: Durch eine Unachtsamkeit im Source 
      wurde unter MiNT doch gepuffert, obwohl dort ja die Erkennung von 
      Eingaben nicht klappt.
    - TOS2GEM kann jetzt auch zeitgesteuerte Ausgabepufferung, dabei 
      erfolgt der Refresh im vorgegebenen Zeitintervallen. Erreicht wird 
      dies durch negative Werte im Cookie-Element buffer_output.
    - Der Zeilenredraw im Farbmodus wurde auf die "flackerfreie" Methode 
      umgestellt, die zwar etwas langsamer, dafr aber augenfreundlicher 
      ist.

    TOS2GEM-Beta vom 07.04.1995
    - TOS2GEM kann jetzt auch die Farbsequenzen (wozu ich auch die zum 
      Invertieren zhle)! Das neue Cookie-Element color bestimmt dabei die 
      Art der Farbuntersttzung (kompatibel oder VDI-konform). Nheres dazu 
      in der .HYP-Doku, die ja jetzt freigegeben ist.
    - Unter SingleTOS benutzt TOS2GEM jetzt bei Ausgabepufferung zustzlich 
      bei Bconstat-Aufrufen einen Timer, der nach 500ms einen Refresh 
      auslst. Damit funktionieren auch TOS-Programme, die die Tastatur per 
      Bconstat/Bconin abfragen, korrekt (z.B. SYSOK). Unter MagiC ist das 
      nicht ntig, da hier sowieso bei jedem Bconstat-Aufruf der Puffer 
      geleert wird.

    TOS2GEM vom 24.03.1995
    - Da mir in einem Bugreport berichtet wurde, da der TOS2GEM-Cookie 
      auch nach einem Reset noch vorhanden ist, klinkt sich TOS2GEM jetzt 
      auch dann in den Reset-Vektor ein, um den Cookie-Pointer zu lschen, 
      wenn es den Cookie-Jar nur erweitern mute. Hoffentlich ist das 
      Problem damit behoben (ich konnte es nicht nachvollziehen).
    - Bei aktiver Ausgabepufferung wird jetzt auch dann ein "Refresh" 
      durchgefhrt, wenn sich der Bildschirminhalt (intern) um seine 
      vertikale Gre verschoben hat. Auf diese Weise werden keine Ausgaben 
      mehr komplett verschluckt.

    TOS2GEM-Beta vom 02.02.1995
    - Jetzt klappt das Erkennen von Tastatur-Eingaben auch unter MagiC, 
      also ist die Pufferung auch mit diesem Betriebssystem mglich. Leider 
      geht es nicht mit MiNT/MultiTOS (hier wird man aber sowieso zugunsten 
      von TOSWIN/MINIWIN auf TOS2GEM verzichten, was natrlich auch fr 
      VT52 unter MagiC gilt)
    - Die Pufferung konnte nochmals verbessert werden, so da die Ausgabe 
      etwas mehr als doppelt so schnell als ohne Pufferung erfolgt (das ist 
      zum Teil schneller als die Standard-GEMDOS/BIOS-Ausgabe)

    TOS2GEM-Beta vom 31.01.1995(?)
    - Durch das neue Cookie-Element buffer_output kann eine Pufferung der 
      Ausgabe erzielt werden, was einen deutlichen Geschwindigkeitsgewinn 
      bringt. Leider klappt das nur mit SingleTOS, weil TOS2GEM nur dort 
      korrekt Eingaben von der Tastatur erkennen kann (in diesem Fall mu 
      ja der Puffer geleert werden, damit man sieht, was man berhaupt 
      eingeben soll)

    TOS2GEM vom 19.01.1995
    - Mute TOS2GEM den Cookie-Jar anlegen oder erweitern, ging dieser 
      bei der ersten Aktivierung der Ausgabeumlenkung verloren, da er im 
      gleichen Speicherbereich wie die VDI-Arrays lag.

    TOS2GEM vom 03.01.1995
    - Bei der Reaktivierung der Ausgabebumlenkung mittels switch_output 
      wurde y_offset nicht korrekt angepat. Da dies ein nicht 
      unerheblicher Fehler war, ist es ratsam, in Programmen, bei denen das 
      TOS2GEM-Fenster in der Gre gendert werden kann, mindestens diese 
      TOS2GEM-Version vorauszusetzen (Cookie-Element date beachten!)
    - TOS2GEM.PRG hat jetzt wieder das Speicherschutzflag "Global" (hatte 
      ich das letzte Mal vergessen, weil der Pure C-Linker das ja leider 
      nicht kann (zumindenst nicht der von PC 1.0))
    - Die Headerdatei wurde verbessert: Fr das reserved-Feld des Cookies 
      existiert jetzt die Konstante RESERVED_SIZE, die die Gre des Feldes 
      angibt.

    TOS2GEM vom 12.12.1994:
    - Bei der Berechnung zweier interner Variablen war mir ein kleiner 
      Fehler unterlaufen, der unter bestimmten Umstnden zu fehlerhaftem 
      Scrolling fhrte (wenn von einer Zeile nur die erste Pixelreihe 
      sichtbar war)
    - TOS2GEM-Beispiel in's "groe" Archiv aufgenommen, damit man sich auch 
      ein Bild davon machen kann, welchen Zweck TOS2GEM berhaupt hat und 
      wie es arbeitet. Daran hatte ich zuerst nicht gedacht (Dank an Dirk 
      Klemmt, der mich auf dieses Versumnis hingewiesen hat).

    TOS2GEM vom 22.11.1994:
    - Erste offizielle Version, leider noch ohne ST-Guide-Doku (ich wollte 
      TOS2GEM halt auf der proTOS "releasen"...)
    - Unter MagiC wird jetzt das Problem umgangen, da ein Aufruf von Fread 
      fr die Console den "echten" Cursor einschaltet und den von TOS2GEM 
      vllig falsch plaziert. Die Lsung ist zwar unsauber (Schreibzugriff 
      auf die negativen LineA-Variablen), allerdings habe ich keine andere 
      verlliche Methode gefunden.
    - TOS2GEM hat jetzt das Speicherschutz-Flag "Global", damit es in 
      dieser Hinsicht keine Probleme mit MiNT/MultiTOS gibt.

