                               Liberty

                      Anwenderdokumentation 0.1
                              01.06.1996

                                 von

                           Christian Krger
                           Im Erpelgrund 16
                             13503 Berlin

                  Internet: chrisker@cs.tu-berlin.de



Inhaltsverzeichnis
==================

 1  Rechtliches / Copyright
    1.1  Haftungsausschlu
    1.2  Warenzeichen
    1.3  Spenden

 2  Installation
    2.1  Bootreihenfolge

 3  Was ist Liberty?

 4  Was bietet Liberty?
    4.1  CJar-Erweiterung
    4.2  Vektorgrafikfunktionen

 5  An die programmierenden Zunft

 6  Ausblick

 7  Kontaktadresse



1  Rechtliches / Copyright
**************************

Das Copyright  an Liberty und dieser Dokumentation liegt bei Christian
Krger, Berlin. Die Weitergabe des Programms  ist  Grundstzlich  frei
(Stichwort FREEWARE), dennoch sind folgende Punkte zu beachten:

    Das  Programm  darf  nur  mit  allen  zugehrigen  Dateien und in
     *unvernderter* Form weitergegeben werden.  Entweder  unkomprimiert
     oder als 'Zip'-Archiv. Folgende Dateien mssen folglich im Archiv
     enthalten sein (-> = Ordner):



           LIBERTY -> AUTO        -> LIBERTY.PRG
                      DOKU        -> HTML         -> LIBERTY.HTM
                                                     LIBERTY.GIF
                                                     MYSELF.GIF
                                                     UDO_LF.GIF
                                                     UDO_RG.GIF
                                                     UDO_UP.GIF
                                     LIBERTY.TXT
                                     LIBERTY.HYP
                      SIZEJAR.TTP


    Das Programm darf generell nur  kostenlos  weitergegeben  werden.
     Der  Upload  in gebhrenfreie Mailboxen und auf nichtkommerzielle
     FTP-Server ist erlaubt und erwnscht.

    Dem Archiv drfen  keine  weiteren  Dateien  hinzugefgt  werden,
     insbesondere  keine  Mailboxwerbung  und  keine  Werbung  fr PD-
     Serien.  Die  Umbenennung  oder  das  Umpacken  des  Archivs  ist
     unerwnscht.

    Das  Programm darf anderen Programme beigelegt werden - unter der
     Voraussetzung,   da   ich   *vor   der   Verffentlichung* darber
     informiert  werde  und  ein eindeutiger Hinweis auf die Versions-
     nummer   der   beigefgten    Liberty-Version    erfolgt    (z.B.
     hervorgehoben im 'README').
     Auch hier gilt obiges 'Vollstndigkeitsprinzip'!

    Fr  die  Weitergabe auf Disketten im Rahmen einer Public-Domain-
     Serie drfen keine Gebhren verlangt werden, die einen Betrag von
     10 DM (exklusive Versandkosten) berschreiten.

    Die  Weitergabe  via  CD-ROM  darf  nur  dann  ohne  schriftliche
     Genehmigung erfolgen,  wenn  der  Preis  der  CD  pro  bespieltem
     MegaByte 0.1 DM nicht bersteigt!


1.1  Haftungsausschlu
======================

Trotz sorgfltiger  Entwicklung  und  umfangreichen  Tests  kann keine
Gewhrleistung fr die Richtigkeit des  Inhalts  dieser  Dokumentation
und die einwandfreie Funktion von "Liberty" bernommen werden.

Der Autor kann keine Haftung fr irgendwelche direkten oder indirekten
Schden - einschlielich aber nicht  beschrnkt  auf  materielle  oder
finanzielle  -  bernehmen, die durch die Benutzung von "Liberty" oder
dessen Untauglichkeit fr einen bestimmten Zweck entstehen.


1.2  Warenzeichen
=================

Innerhalb dieser Dokumentation wird auf Warenzeichen  Bezug  genommen,
die  nicht  explizit als solche ausgewiesen sind. Aus dem Fehlen einer
Kennzeichnung kann nicht geschlossen werden, da ein Name frei von den
Rechten Dritter ist.


1.3  Spenden
============

Wie schon    erwhnt    ist    Liberty   Freeware.   Ich   habe   aber
selbstverstndlich nichts gegen TOS-Programmentwicklungssttzungskufe
;-).  Wer  mit  also eine motivationssteigernde Spende zukommen lassen
mchte, kann das ber die Kontaktadresse tun.
Wer keine Lust hat etwas zu  spenden  und  trotzdem  meine  Motivation
steigern  mchte,  der sollte sich 'Freedom2' kaufen. Dann bekommt man
wenigstens etwas fr's Geld ;-) ...



2  Installation
***************

*(Bitte dieses Kapitel komplett _vor_ der Installation durchlesen!)*

Kopieren Sie einfach 'LIBERTY.PRG'  in  den  AUTO-Ordner  ihres  Boot-
Laufwerkes.

Nach dem  Kopieren  von  'LIBERTY.PRG'  und  dem folgenden Systemstart
installiert sich dann die Library automatisch.


2.1  Bootreihenfolge
====================

'LIBERTY.PRG' sollte  physikalisch  mglichst  frh   im   AUTO-Ordner
stehen,  auf  jeden  Fall vor (wenn Sie es denn einsetzen) MiNT! Viele
Bootselektoren   (z.B.   XBOOT)   erlauben   es,    konfortabel    die
Bootreihenfolge  der  AUTO-Ordner  Programme zu verndern. Sollten Sie
nicht in Besitz eines solchen Programms sein hilft folgendes:
Betrachten Sie sich  ihren  AUTO-Ordner  im  Desktop  in  unsortierter
Ausgabeart. Hier sollte 'LIBERTY.PRG' mglichst weit vorne stehen. Ein
ndern  der  Bootreihenfolge  erreichen  Sie  durch  Verschieben   des
kompletten   AUTO-Ordners   in   ein   anderes   Verzeichnis  und  dem
Zurckverschieben   aller   AUTO-Ordner-Programme    in    gewnschter
Reihenfolge  in  den  AUTO-Ordner. (Wer absolut nicht versteht was ich
meine,  kann  mich  unter  spter  genannter  Adresse   kontaktieren.)
MagiCMac  Benutzer  mssen  den Umweg ber Umbenennen der Dateien oder
Bootreihenfolgedatei (wie in der MagiCMac  Dokumentation  beschrieben)
gehen  um  Liberty  mglichst  frh  zu  initalisieren (MiNT wird wohl
keiner auf Macs benutzen ;-) ).



3  Was ist Liberty?
*******************

LIBERTY ist eine residente Systemerweiterung. Das bedeutet,  da  eine
Vielzahl  von  Funktionen  die  in  LIBERTY  vorhanden  sind,  anderen
Programmen angeboten  werden.  Das  bloe  Vorhandensein  von  LIBERTY
ndert  nicht viel an Ihrem System, sondern die Funktionen der Library
(oder auch Systemerweiterung, folgend Lib genannt) mssen von  anderen
Programmen  genutzt  werden.  Freedom2  ist z.B. ein solches Programm.
Freedom2 benutzt viele der Liberty-Funktionen, so da  es  ohne  diese
Lib nicht lauffhig ist.

Nun gibt  es  (oft  zurecht) viele Gegner solcher Systemerweiterungen.
Die Argumente gegen den  Einsatz  einer  residenten  Erweiterung  sind
meistens folgende:

    residente  Systemerweiterungen schlucken permanent Speicher, auch
     wenn sie nicht bentigt werden

    residente Systemerweiterungen  werden  oftmals  nur  von  wenigen
     Programmen  untersttzt  und  viele  Funktionen  der  Erweiterung
     werden nicht bentigt, was dann  ebenfalls  Speicherverschwendung
     bedeutet

    residente  Systemerweiterungen  sind gro, klobig und unflexibel;
     bei  Zugriff  von  mehreren  Programmen  auf  eine  Funktion  der
     Erweiterungen   gibt  es  oft  Probleme  oder  der  Rechner  wird
     'gebremst' (Experten mgen mir verzeihen, da ich hier nicht  von
     Semaphoren spreche :-) )

Die Vorteile solcher Erweiterungen:

    das  'Rad'  mu  nicht  tausendmal neu erfunden werden; Programme
     knnen die angebotenen Funktionen einfach benutzen ohne zu wissen
     was  sie  genau  machen  (daraus  folgt  eine  wesentlich krzere
     Entwicklungszeit und (hoffentlich) mehr Spa am Programmieren, da
     man  sich  auf  die  programmspezifischen  Probleme konzentrieren
     kann)

    benutzen viele Programme  die  Systemerweiterung  gibt  es  einen
     Speicherspareffekt: die von vielen Programmen bentigten Routinen
     der Systemerweiterung sind nur einmal im Speicher  und  nicht  in
     jedem der Programme extra vorhanden.

LIBERTY hat  natrlich  diese  Vorteile  und entkrftet zustzlich mit
seiner Art des Aufbaus die Nachteile:

    Liberty verbraucht weniger als  25kB  Speicher!  (ist  also  kein
     'grober  Klotz'  wie  andere  Libs  die gleich 300kB oder mehr an
     Speicher verschlingen)

    Liberty konzentriert  sich  auf  die  wesentlichsten  Mankos  des
     Betriebsystems  und  beseitigt  sie;  es ist keine GEM-Interface-
     Library! (wre wohl  auch  sinnlos  zu  versuchen  alle  GEM-Lib-
     Programmier- Sppchen zu einem Standard zu vereinigen ;-) )

    fast  alle  Funktionen  der  Lib werden von Freedom2 benutzt (wer
     kommt schon ohne aus? ;-) ); von Speicherverschwendung  kann  bei
     Einsatz  von  Freedom2 folglich nicht gesprochen werden (bei 25kB
     ist dieses ohnehin schon  ziemlich  unglaubwrdig);  bereits  bei
     Einsatz  eines  zweiten  Programms welches Liberty benutzt, tritt
     der gewnschte Speicherspareffekt ein

    Liberty besteht zu 90%  aus  hochoptimierten  Assembler-Routinen;
     nur  so  konnte  die  Krze  und  Geschwindigkeit der Erweiterung
     erreicht werden

    alle Funktionen von Liberty sind reentrant und 95% der Funktionen
     sind   'Multi-Threading'-fhig  (d.h.  mehrere  Programme  knnen
     gleichzeitig eine Funktion von Liberty benutzen ohne  sich  dabei
     gegenseitig zu stren oder zu blockieren)

berzeugt?



4  Was bietet Liberty?
**********************

Liberty setzt   sich   aus   Funktionen  mit  den  unterschiedlichsten
Aufgabengebieten   zusammen.   Obwohl   daher   das   Funktionsangebot
vielleicht  etwas  zusammengewrfelt  scheint,  ist  dem nicht so. Wie
schon  erwhnt  versucht  Liberty   die   nervensten   Schwchen   des
Betriebsystems    auszugleichen:    Funktionen,   die   immer   wieder
programmiert oder eingebunden werden mssen und  die  viele  Programme
bentigen.  Das diese Schwchen nicht konzentriert an einer Stelle des
Betriebssystems auftreten ist logisch. So besteht die Lib  intern  aus
folgenden Teilen:

    XBIOS-Erweiterung:

        CJar-kompatibele  XBIOS Erweiterung, die auf komfortabele
         Weise das Erzeugen, Abfragen und  Lschen  von  'Cookies'
         ermglicht

    Erweiterungen mit GEMDOS-Charakteristik:

        eine sehr effiziente und schnelle Speicherverwaltung, die
         privaten, globalen, normalen  und  alternativen  Speicher
         (wenn ntig) unterscheidet und kleinere Speicherblcke in
         greren verwaltet sowie fr  ein  dauerhaftes,  sicheres
         'malloc' fr ACCs unter SingleTOS sorgt

        eine  Routine  zum  Laden  einer  Datei  in  einen Puffer
         (sollte die Datei mit ATOMIK 3.5 gepackt  sein,  so  wird
         diese automatisch ausgepackt!)

    Erweiterungen mit VDI-Charakteristik:

        eine  Vielzahl  von sehr schnellen Rastergrafikfunktionen
         (Laden von XIMG/GIF, Skalieren etc.)

        Vektorgrafikfunktionen      (Translation,       Rotation,
         Skalierung,  ...)  -  damit sind endlich auf einfache und
         komfortabele Weise Vektoricons realisierbar

    AES-Untersttzung:

        Funktionen zum  einfachen  Einhngen  von  Funktionen  in
         einzelne AES- Calls (mit Applikationszustandslisten!)

        LIBERTY  ist in der Lage (auch wenn kein Programm Liberty
         benutzt) defekte AES-Calls (nicht initalisiertes  Global-
         Field)  zu reparieren! Damit wird u.a. erreicht, da z.B.
         der      Dateiselektor       Freedom       auch       von
         ('Schweine'-)Programmen aufgerufen werden kann, bei denen
         sonst die normale Dateiauswahlbox erscheinen wrde!


4.1  CJar-Erweiterung
=====================

Liberty legt beim Start im AUTO-Ordner automatisch einen  'Cookie-Jar'
an.  Programme  die  dieses  sonst bernommen haben ('CJARxxx.*' etc.)
sind damit berflssig! Ebenfalls, das fr den MiNT  Aufsatz  'Geneva'
bentigte  'JARxxx.PRG'  ist  unntig. In Liberty sind die Fhigkeiten
dieses Programms enthalten! (JARxxx wurde getestet, fr  gut  befunden
und die Funktionalitt (erweitert) aufgenommen.)

Die Gre   des   'Cookie-Jar'   kann  mit  dem  beigefgten  Programm
'SIZEJAR.TTP' verndert werden.  In  der  Grundeinstellung  wird  beim
Start   von  Liberty  fr  32  zustzliche  'Kekse'  (zu  den  aktuell
vorhandenen Systemcookies) Platz  geschaffen.  Diesen  Wert  kann  man
wiefolgt ndern:

  1. Man kopiert 'SIZEJAR.TTP' in das Verzeichnis in dem 'LIBERTY.PRG'
     steht (also normalerweise in den AUTO-Ordner).

  2. Man startet das Programm durch  Doppelklick  und  gibt  dann  die
     gewnschte  Anzahl an Keksen als Zahl in den erscheinenden Dialog
     ein.

  3. Nach Beendigung des Programms mu man  'SIZEJAR.TTP'  wieder  aus
     dem AUTO-Ordner entfernen.

  4. Beim   Neustart  des  Systems  bercksichtigt  dann  Liberty  die
     angegebene Anzahl. Fertig!

In der Regel  sollte  dieses  Vorgehen  jedoch  unntig  sein,  da  32
(zustzliche)     Kekse    ausreichen    und    auch    keine    groe
Speicherverschwendung darstellen.


4.2  Vektorgrafikfunktionen
===========================

Vektorzeichenstze und   Bezierkurven    sollten    heutzutage    eine
Selbstverstndlichkeit  sein.  So  werden  diese  Befehle auch von den
Vektorgrafikfunktionen in Liberty  ordnungsgem  verarbeitet.  Leider
ist  das  Original-VDI (der Betriebssystemteil der fr die Ausgabe von
Grafiken verantwortlich ist)  nicht  in  der  Lage  diese  Befehle  zu
verarbeiten und ignoriert sie vllig.
Das  bedeutet,  da  wenn  ein  Programm die Vektorgrafikdarstellungs-
funktionen  von  Liberty  benutzt  und   die   darzustellende   Grafik
Bezierkurven und/oder Vektorzeichenstze enthlt, das Ergebnis auf dem
Bildschirm nicht der Originalgrafik  entspricht.  Dieses  trifft  aber
selbstverstndlich nur fr VDIs zu, die diese Befehle nicht verstehen!
Wie  alle  Funktionen von Liberty sind auch die Vektorgrafikfunktionen
auf Geschwingidkeit getrimmt. Bei der Vektorgrafikausgabe  wurde  z.B.
ein  groer  Geschwindigkeitsvorteil dadurch erreicht, da die Ausgabe
_direkt_ an das VDI geleitet wird und die Befehle nicht erst durch einen
TRAP  geschickt werden! Das dabei verwendete Verfahren ist keinenfalls
'schweinisch' sondern bekannt! (Fr die Experten: Man ld das Register
D0  mit -1 und macht einen TRAP #2 Aufruf. Als Ergebnis erhlt man die
Einsprungsadresse des VDI-Dispatchers.)
VDI-Erweiterungen,   die   das    VDI    hinsichtlich    z.B.    einer
Bezierkurvenausgabe  erweitern,  mssen  dieses Verfahren untersttzen
(Profibuch, 10. Auflage, Seite 298 unten)!

'NVDI' (da sauber) hat damit keine  Probleme  und  in  Verbindung  mit
diesem  VDI  klappt  die  Ausgabe  obiger Befehle wunderbar (auch wenn
'NVDI' nur  als  GDOS  eingesetzt  wird)!  Leider  kann  man  das  vom
'SpeedoGDOS'   nicht  behaupten.  Diese  VDI-Erweiterung  versumt  es
offensichtlich obiges Verfahren zu untersttzen und somit  ist  dieses
Ausgabesystem   fr   Liberty   praktisch   nicht   vorhanden   (keine
Bezierkurven und keine Vektorzeichenstze!!!).

Ich wei,  da  diese  Tatsache  sicherlich  einige   Leute   ziemlich
verrgert und mchte deshalb hier Forderungen nach 'konformer' Ausgabe
ber den TRAP vorbeugen:

    die oben beschriebene Vorgehensweise ist konform, da sie  bekannt
     ist  und  es  offensichtlich  auch ein Ausgabesystem gibt (NVDI),
     welches  damit  keine  Probleme   hat;   Liberty   ist   folglich
     unschuldig,  das Problem liegt beim unvollstndigem Ausgabesystem
     (SpeedoGDOS)

    ein Abndern der Liberty-Vektorgrafikausgabe brchte  unzumutbare
     Geschwindigkeitseinbuen     fr     Benutzer    mit    konformen
     Ausgabesystemen

    ich  habe   wenig   Lust   die   Fehler   anderer   Programmierer
     auszubgeln...

Meine Empfehlung an SpeedoGDOS-Fanatiker die programmieren knnen:
Programmiert  ein  Utility  welches  sich in den TRAP #2 hngt, die -1
abfngt und die Adresse des SpeedoGDOS-Dispatchers zurckliefert. Dann
klappt's auch mit Liberty... ;-)



5  An die programmierenden Zunft
********************************

Sie sind  Programmierer,  die  Featureliste von Liberty hat Sie locker
vom Hocker geworfen und Sie sagen sich:"Eine tolle Library,  die  will
ich  auch  untersttzen!"  Kein  Problem (wenn Sie in PureC/PurePascal
programmieren) - treten  Sie  vertrauensvoll  mit  mir  in  Verbindung
(siehe  "Kontaktadresse")  und  ich werde sehen was ich tun kann! Eine
Dokumentation fr Programmierer ist in Arbeit und wird (auch  abhngig
von der Resonanz) bestimmt bald fertig sein.

Einzige Voraussetzung  um  die Library benutzen zu drfen: Ich erhalte
ein kostenloses Exemplar des Programms welches  die  Library  benutzt!
Software  die  den  Status 'Public Domain', 'Freeware' oder 'Fairware'
hat, ist davon natrlich ausgenommen ;-).



6  Ausblick
***********

Zum Zeitpunkt dieser ersten Verffentlichung von  'Liberty'  sind  die
Rastergrafikfunktionen  leider  alles  andere als komplett. Damit aber
andere schon jetzt zumindest  in  den  Genu  der  restlichen  Liberty
Funktionen  kommen,  habe  ich  mich  dennoch  fr  die Herausgabe der
Library im nicht vollstndigem Zustand entschieden.
Erste Erweiterung wird folglich darin bestehen,  den  Rastergrafikteil
vollstndig  auszubauen.  Aber  auch  im  Vektorgrafikteil fehlen noch
einige wnschenswerte Zusatzfunktionen.

Wie danach  die  Weiterentwicklung  verluft  ist  schwer  zu   sagen.
Hauptschlich   hngt   das   von   meinen  eigenen  Bedrfnissen  ab.
Selbstverstndlich  knnen  auch  Wnsche  anderer  Programmierer  die
Liberty  nutzen  (wollen)  den Funktionsumfang erweitern. Jedoch werde
ich strikt darauf achten,  da  Liberty  nie  mehr  als  50k  Speicher
schluckt und nicht zum schon beschriebenen 'Klotz' wird.

Welche Funktionen   Liberty   bietet  kann  dem  'einfachen'  Anwender
eigentlich egal sein. Er  kommt  meist  unbemerkt  in  den  Genu  der
Funktion,  sobald  ein  Programm  sie  benutzt. Das einzige worauf ein
Anwender  achten  sollte  ist,  da  er  mglichst  immer  die  neuste
Liberty-Version  installiert  hat.  Da  Liberty benutzenden Programmen
beigefgt werden darf, drfte diese Forderung leicht zu erfllen sein.



7  Kontaktadresse
*****************

Falls Sie irgendwelche Fragen, Probleme oder Wnsche bezglich Liberty
haben sollten, knnen Sie mich unter folgender Adresse erreichen:

Christian Krger
Im Erpelgrund 16
13503 Berlin

Internet email: chrisker@cs.tu-berlin.de

*Wichtig:* Wer  Kontakt  via  Sackpost zu mir aufnehmen will, der sollte
(wenn er  eine  Antwort  erwartet)  einen  an  sich  adressierten  und
ausreichend frankierten Rckumschlag beifgen!
Von  privaten  Besuchen  bitte  ich abzusehen, die Erfolgschancen mich
anzutreffen sind ohnehin ziemlich gering.
Auerdem bitte ich alle Anwender der Library nur dann zu  mir  Kontakt
aufzunehmen,  wenn  unlsbare Probleme oder gravierende Mngel bei der
Installation der Library auftreten! (Ich  verstehe  darunter  das  man
sich  mindestens  2x  die  Liberty- Dokumentation durchgelesen hat und
immernoch nicht schlauer ist!!!)
Zeit die ich mit der Beantwortung von Fragen verbringe steht mir nicht
mehr  zum  Programmieren  zur  Verfgung... (Ein gutes und hilfreiches
Forum um solche Fragen evt. zu klren stellt die "Hotline  der  Share-
/Freeware",  das  Maus-Netz, Gruppe 'atari.soft' dar. Wren hier nicht
viele hilfsbereite und kompetente Menschen zugegen, die bei Fragen  zu
Programmen   durch   ihre   Beantwortung   fr   die   Programmautoren
einspringen, wer wei ob Liberty htte jemals entstehen knnen...  Ich
widme  daher  diese  Library  allen  Atari-Enthusiasten im Maus-Netz -
*Danke!* :-) )

/Rchtzszeibunsflr by Zeitmangel./



