HyperText

HyperText is a text-only very fast hypertext engine for the Atari ST. All the files can be found on GitHub.

∑-Soft ~~Birkhahnkamp 38~~ ~~2000 Norderstedt 1~~ 05.12.1992

~~Tel: 040–5223955~~ ~~FAX: 040–5263307~~ ~~BBS: 040–5267185 (300–14400 Baud 8N1, MNP 1–5, V32(bis), V42(bis), HST)~~

Sehr geehrte Damen und Herren,

Wir bedanken uns für den Erwerb von HyperText. Sie dürfen HyperText zusammen mit den Druckertreibern beliebig ihren Programmen beilegen. Aus der Anleitung sollten sie nur das nötigste zusammenstellen und ebenfalls ihren Kunden zur Verfügung stellen. Ein Abdruck in ihrer Anleitung zu ihren Programmen ist ausdrücklich erlaubt. Den Help-Compiler dürfen sie jedoch NICHT weitergeben!

Beachten Sie auch, daß Sie für jedes Produkt, welches Sie mit HyperText ergänzen, ZWEI nicht eingeschränkte Originale an Sigma-Soft schicken müssen. Weitere Lizenzgebühren sind NICHT fällig! Wer dies jedoch aus bestimmten Gründen nicht kann bzw. will, weil das Programm z.B. 30000,- DM kostet, dermuß uns für jedes verkaufte Exemplar von diesem Programm 10,- DM zukommen lassen!

Eine wichtige Änderung am Help-Compiler: Ab sofort kann man normale Hilfstexte auch OHNE 1st Word Plus eingeben! Die Seiten müssen dazu lediglich durch eine “~” am Zeilenanfang getrennt werden. Dies verbietet natürlich die Verwendung einer “~” am Zeilenanfang. Wer sie unbedingt darstellen will, muß lediglich 126 am Zeilenanfang eingeben. ist ein sog. ESC-Code. Die drei Ziffern dahinter geben den ASCII-Code an. Damit kann man problemlos sämtliche 255 Zeichen aus dem ASCII-Code darstellen.

Falls ihnen mal ihr Originaltext verloren geht, so ist es möglich aus der HYP-Datei wieder einen ASCII-Text zu erzeugen. Wir haben soetwas schon einmal machen müssen. Jedoch ist dieser “Recompiler” mit der aktuellen Version nicht mehr funktionsfähig, so daß er überarbeitet werden müßte. Das kostet Zeit und Geld. Aber falls ihnen der Originalsource verloren gegangen ist, würden wir versuchen ihnen zu helfen.

So, nun noch einige Bemerkungen zur Version 1.1 von HyperText. In dieser Version sind im wesentlichen folgende Fehler behoben worden:

  • So wurde Fclose() mehrfach aufgerufen! Es konnte somit passieren, daß eine falsche Datei geschlossen wurde! (jaja, das GEMDOS ist sehr fehlertolerant, wenn fremde Prozesse einem die Datei schließen…)
  • Anpassung an die neuere XAcc-Doku 1.1. Beim Start von HyperText als Accessory meldet sich HyperText mit ACC_ID für ein eventuelles Autostart- Programm (ab TOS 1.04).
  • Lesezugriffe auf das SR-Register vom Prozessor entfallen, obwohl durchaus erlaubt. Aber einige unsaubere Programme (z.B. GFA-Basic) verbiegen auf dem TT einen Vektor, der diese Opcodes unmöglich macht. Dies ist kein Fehler von HyperText!

Bei TOS 2.0x kann es nach der Benutzung der Slider zu Abstürzen kommen. Dies ist ein Fehler im TOS 2.0x und NICHT in HyperText! Der Fehler wird durch das Programm ARROWFIX V1.1 behoben. Aus rechtlichen Gründen dürfen wir es nicht beilegen, es ist wohl in diversen Mailboxen und über Atari zu beziehen.

Die maximale Länge einer Seite in HyperText liegt bei 64K. Dies ist genaugenommen eine Beschränkung des Help-Compilers und nicht von HyperText. Wer es unbedingt braucht, soll sich mit uns in Verbindung setzen. Da beim Springen zu Stichwörtern aber nur an den Seitenanfang gesprungen wird, sollte man solche Seiten vermeiden. Zudem sollte die Seite eh möglichst nie wesentlich länger als eine Bildschirmseite sein, der User will Hilfe zu einem Punkt und keine Roman lesen.

Die maximale Anzahl der Stichwörter liegt bei 4096. Wer mehr braucht, kann eine spezielle Version des Help-Compilers erhalten. Jedoch ist zu bedenken, daß der Help-Compiler dann erheblich mehr Speicher benötigt!

Mit freundlichen Grüßen,

Markus Fritze, ∑-Soft

German Manual for HyperText 1.1d

©1990–2 ∑-Soft, Christoph Pagalies und Markus Fritze

Einführung

HyperText ist ein System, das Hilfstexte möglichst komfortabel anzeigt. Es kann sowohl “Stand-Alone-Texte” bearbeiten, als auch zusammen mit Programmen verwendet werden, die damit eine Hilfestellung realisieren.

Die wesentlichen Vorteile eines Hilfstextes auf dem Computer gegenüber dem auf Papier sind,

  • daß der Text sofort zur Hand ist, und man nicht erst nach der Anleitung kramen muß,
  • daß die Hilfestellung kontextsensitiv erfolgt, d. h., daß Hilfe zu genau dem Thema angeboten wird, bei dem Probleme aufgetreten sind. Das Suchen des richtigen Kapitels entfällt,
  • daß der Text sehr schnell nach verschiedenen Methoden durchsucht werden kann,
  • daß man sehr schnell zu anderen Themen springen kann, ohne seine Finger in einem Buch verteilen zu müssen.

Diese Anleitung beschreibt HyperText in der Version 1.0d. Eine englische Version ist auch erhältlich.

HyperText ist ein SHAREWARE-Programm. Wer diese TOS-Dokumentation mag und verwendet, sollte uns 20,- DM zukommen lassen.

Wer selbst Texte für HyperText schreiben will, kann für 50,- DM zzgl. Porto und Verpackung (In Deutschland 5,- DM bei Vorkasse, 15,- DM bei Nachnahme, Ausland nur Vorkasse möglich, dort 10,- DM) ein Programm erwerben, welches 1st Word Plus Texte in HyperText-Texte wandelt. Auf der Diskette befindet sich dann auch der originale 1st Word Plus Text zu dieser TOS-Doku (zum Ansehen, Ändern und Lernen), sowie die englische Version von HyperText. Wer HyperText in eigenen Programmen verwendet, hat keine Lizenzgebühren zu entrichten, lediglich 2 Originale des Programms an ∑-Soft zu schicken. Der Konverter ermöglicht auch das Einbinden eines eigenen Copyright-Dialoges in HyperText. Der Konverter ist KEIN PD- bzw. Shareware-Programm und darf NICHT weitergegeben werden!

∑-Soft
HyperText
xxxxxxx xx
2000 Norderstedt 1
Konto-Nr xxxxxxx, BLZ 20069111 (Norderstedter Bank)
Tel: (040)xxxxxxx
FAX: (040)xxxxxxx
BBS: (040)xxxxxxx 300-14400 Baud, 8N1, MNP, V32bis, V42bis, HST

Über unsere Mailbox kann man auch Updates von HyperText downloaden. Registrierte Konverter-Besitzer erhalten neben Updates für den Konverter auch Unterstützung bei Problemen.

Die Bedienung

Der Anfang ist einfach: Starten Sie HyperText als Programm, oder installieren Sie es als Accessory. Das Programm kann in beiden Modi verwendet werden; nur die Extension ist entsprechend zu ändern.

Nach dem Start öffnet HyperText ein Fenster, in dem die Startseite zu sehen ist. Oben am Rand sehen Sie eine Reihe von Buttons, auch unten können sogenannte Bill-Buttons erscheinen. Diese werden in den folgenden Abschnitten behandelt.

Kurz grundlegendes zum Konzept von HyperText:

Jeder Hilfetext besteht aus einer Reihe von Seiten. Diese ist nicht unbedingt identisch mit einer Bildschirm- oder Druckerseite, sondern es ist nur eine logische Unterteilung. Auf dem Bildschirm sehen Sie jeweils die aktuelle Seite, auf der ein Stichwort erklärt wird. In dieser Erklärung können weitere Stichwörter auftauchen, die auf anderen Seiten beschrieben sind. Diese Wörter erkennen Sie daran, daß sie fett geschrieben sind.

Wenn Sie nähere Erläuterungen zu einem dieser weiteren Stichwörter wünschen, klicken Sie einfach mit der linken Maustaste auf das fett geschriebene Wort — und es wird zu der entsprechenden Seite verzweigt. Das Stichwort, daß auf der aktuellen Seite erklärt wird, ist fett und unterstrichen dargestellt; auf dieses können Sie nicht klicken.

Haben Sie die “tieferliegende” Erklärung nun durchgelesen und möchten zur “darüberliegenden” zurück, so drücken Sie einfach die Undo-Taste oder klicken Sie mit der rechten Maustaste auf eine beliebige Stelle. Wenn Sie dieses mehrfach ausführen, können Sie bis zu 20 Ebenen zurückblättern.

2.1 Der “Atari”-Button

Der Button oben links ruft die Info-Box auf. Sie gibt Ihnen Auskunft darüber, welchen Text Sie gerade lesen und von wem er vertrieben wird. Mit “OK” können Sie diese Box wieder verlassen, die “Info”-Box führt zu der ∑-Soft Info-Box.

2.2 Die Pfeil-Buttons und die Seitenzahl

Rechts daneben sehen Sie zwei Pfeile mit einer Zahl dazwischen. Die Zahl stellt die Nummer der aktuellen Seite dar; mit den Pfeilen können Sie unabhängig von irgendwelchen Verweisen vor- bzw. zurückblättern.

2.3 Einstellungen

Mit diesem Button gelangen Sie zu einer Dialogbox, in der Sie Voreinstellungen für HyperText tätigen können.

Die Prozentangabe legt fest, wieviel von Ihrem Hauptspeicher für HyperText belegt werden soll. Sie werden sich jetzt vielleicht fragen: “Warum sollte ich einem Programm mehr Speicher gönnen, als unbedingt nötig?” Die Antwort ist einfach: Wenn HyperText mehr Speicher bekommt, versucht es, bereits gelesene Seiten im Speicher zu halten. Falls Sie später auf diese Seite zurückblättern, muß diese nicht mehr neu von Festplatte oder Diskette geladen werden. Das spart Zeit, insbesondere bei der Ganztextsuche (wird später erklärt).

Diese Einstellung wird nur beachtet, wenn Sie HyperText als Accessory installiert haben. Als Programm gestartet, tut es so, als ob Sie 100% eingestellt hätten.

Für technisch Eingeweihte: HyperText sieht nach der Größe des größten Speicherblocks, und bezieht darauf die Prozentangabe. Bei einem TT mit Fast- und ST-Ram, führt das dazu, daß man z. B. 90% einstellt und hinterher immer noch den halben Speicher frei hat, weil beispielsweise das Fast-Ram genutzt wurde, das ST-Ram aber frei blieb. HyperText belegt natürlich niemals 0% oder wirklich 99,9%, es wird immer eine Mindestreserve berücksichtigt.

Unter “Diverses” finden Sie Grow/Shrinkboxes; das sind die größer bzw. kleiner werdenden Kästchen beim öffnen und schließen von Dialogboxen. Wer sie hübsch findet, kann sie hier einstellen, wer Geschwindigkeitsfanatiker ist, der stellt sie aus.

Darunter befindet sich das sogenannte 8er-Clipping. Wenn dieses eingestellt ist und Sie das Window von HyperText verschieben, “hüpft” innerhalb einer 8er-Rasters, läßt sich also nur ein bißchen ruckeliger bewegen. Dafür wird aber die Ausgabe aus technischen Gründen schneller, als wenn es an eine beliebige Position verschoben würde. Je nach Computertyp macht sich dieses mehr oder weniger stark bemerkbar. Was man nutzen will, ist wieder Geschmackssache.

Mit dem “Speichern”-Button sichert man die Einstellungen. Achtung wenn Sie mehrere HyperTexte haben: Die Einstellungen werden in der Hilfe-Datei, nicht in HyperText gesichert.

Der “Protokoll”-Button führt zu einer weiteren Dialogbox:

2.4 Die Protokoll-Dialogbox

Hier wird das Kommunikations-Protokoll definiert. Hinweis: Dieser Abschnitt ist nur für Profis gedacht. Ändern Sie in dieser Dialogbox nichts, wenn Sie nicht genau wissen, was das bewirkt!

HyperText unterstützt sowohl das XAcc- als auch das Turbo-C-Help-Protokoll. Da beide teilweise die gleichen Messagenummern für unterschiedliche Zwecke verwenden, kann HyperText leider nicht automatisch entscheiden, welches Protokoll nun zu nutzen ist.

Wenn Sie HyperText zusammen mit einem Programm bekommen haben, wird das Protokoll, das dieses unterstützt, schon voreingestellt sein. Andernfalls, oder wenn Sie ein anderes wünschen, können Sie dieses hier ändern. Nach einem Protokollwechsel sollten Sie möglichst schnell das Accessory neu starten, da es das XAcc-Protokoll durcheinander bringt, wenn ein Programm beendet wird, daß nie gestartet wurde, und da beim Turbo-C-Protokoll schon in der Boot-Phase bestimmte Aktionen nötig sind. Achtung: Vergessen Sie nicht, in der Einstellungsbox zu sichern.

Das Turbo-C-Protokoll wird beispielsweise von dem Texteditor “Tempus” unterstützt, bei dem Sie ein Wort mit CONTROL-# übergeben können. XAcc unterstützt u. a. “That’s Write”; nähere Informationen erhalten Sie bei Konrad Hinsen (übers MausNet erreichbar).

Rechts neben dem Protokoll kann die Suchart eingestellt werden. Normalerweise interpretiert HyperText das Wort, das ihm per Protokoll übergeben wurde, als Stichwort; wenn es das Wort nicht findet, wird die Synonymsuche aktiviert. Sie können hier aber auch einstellen, daß mit dem Wort eine Ganztextsuche durchgeführt werden soll.

2.5 Suchen

Wenn Sie Hilfe zu einem Thema suchen, zu dem Sie momentan kein Stichwort auf dem Bildschirm sehen, können Sie es über diese Suchfunktion aufspüren. Wenn Sie auf den Button klicken, erscheint eine Dialogbox, in der Sie einfach den Suchbegriff eintippen. Mit “OK” wird die Suche gestartet.

Ist der Begriff genauso irgendwo definiert, wie Sie ihn eingegeben haben, so springt HyperText sofort zu dieser Seite. Vielfach ist man sich aber unsicher, wie der Begriff nun geschrieben wird oder vertippt sich. Dann werden alle vorhandenen Stichwörter mit dem eingegebenen verglichen. Die acht ähnlichsten werden Ihnen in einer weiteren Dialogbox präsentiert. Diesen Vorgang nennt man Synonymsuche.

Bei kleinen Abweichungen befindet sich der gesuchte Begriff fast immer unter diesen ersten acht; Sie können den richtigen mit dem davorstehenden Button anwählen, dann wird zu der entsprechenden Seite gesprungen. Wenn Sie doch keinen davon meinen, können Sie mit dem Button “Suchen” eine erneute Suche starten oder stattdessen abbrechen.

Wenn Sie einen Text suchen, der kein Stichwort ist, können Sie den ganzen Text nach dem Wort durchsuchen lassen. Drücken Sie dazu statt “OK” auf “Ganztext”. Diese Suchart dauert natürlich wesentlich länger, als wenn nur die Stichwörter durchsucht werden müssen, geht aber trotzdem schneller, als wenn Sie so etwas per Hand in einem Buch durchexerzieren — auch hier zeigt sich ein Vorteil des HyperText-Konzepts.

Sie können in der Dialogbox noch einstellen, wo bei der Ganztextsuche begonnen werden soll. Dies ist für den Fall gedacht, daß Sie einen Begriff an mehreren Stellen im Hilfetext haben, aber nur eine bestimmte Stelle suchen. Im Normalfall sollten Sie die Ganztextsuche beim ersten mal “ab Textanfang” starten und, wenn Sie weitersuchen wollen, “ab der nächten Seite” fortsetzen.

Für die Profis gibt es noch die Möglichkeit, das Verhalten der Synonymsuche zu beeinflussen (betrifft nur die Stichwort-, aber nicht die Ganztextsuche). Im Normalfall ist dies wohl nicht nötig, die Autoren haben schon recht lange an den Werten herumexperimentiert, so daß möglichst brauchbare Resultate erreicht werden. Wer mit diesen Werten zufrieden ist, kann den Rest dieses Abschnittes ruhig überlesen.

Erst einmal eine Erklärung, wie die Synonymsuche Überhaupt funktioniert. HyperText vergleicht der Reihe nach alle Stichwörter mit dem eingegebenen. Zwischen den beiden wird eine sogenannte Levenshtein-Distanz berechnet und erst einmal gespeichert. Am Ende werden die Distanzen sortiert und die acht Einträge mit der geringsten Distanz ausgegeben.

Was ist nun eine Levenshtein-Distanz? HyperText überführt das eingegebene Wort in das jeweilige Stichwort, indem er folgende Aktionen durchführt:

  • Ändern von Groß/Kleinschrift
  • Einfügen eines Buchstabens
  • Löschen eines Buchstabens
  • Austauschen eines Buchstabens gegen einen anderen

Diese Aktionen werden solange wiederholt, bis die Wörter identisch sind. Für jede dieser Aktionen gibt es “Strafpunkte”, die addiert werden. Die Endsumme aller Strafpunkte ist dann die Levenshtein-Distanz. Sie können in der Suchbox unter “Synonyme” oder in der Vorschlagsbox unter “Distanz ändern” eine Dialogbox erreichen, in der Sie die Strafpunktvergabe ändern können. Auch diese Werte können unter “Einstellungen” gesichert werden.

Unter den Strafpunkten können Sie angeben, was in der Vorschlagsbox angezeigt werden soll. Normalerweise sind dies die gefundenen Stichwörter. Wenn Sie gerade mit Levenshtein-Werten herumexperimentieren, kann es sinnvoll sein, davor die Distanzen mit auszugeben. Mit etwas nachdenken läßt sich dann sehr schön nachvollziehen, wie HyperText die Umformungen durchgeführt hat. Danach können Sie sich auch noch die Nummer der Seite anzeigen lassen, auf der das jeweilige Stichwort erklärt ist.

2.6 Drucken

Mit diesem Button können Sie die aktuelle Seite ausdrucken. Dazu wird (wenn vorhanden) ein 1st-Word-kompatibler Druckertreiber benutzt. Dieser muß HYPER.CFG heißen und im gleichen Verzeichnis wie HyperText liegen. Wenn Sie schon 1st-Word benutzen, kopieren Sie einfach Ihren Druckertreiber. Sonst können Sie einen der mitgelieferten Treiber benutzen. Kopieren Sie den passenden für Ihren Drucker und benennen Sie ihn um. Wenn kein Druckertreiber vorhanden ist, druckt HyperText ohne aus; dann werden verschiedene Textattribute nicht berücksichtigt, sondern nur reiner ASCII-Text ausgedruckt.

Achtung: Bei Atari-Laserdruckern muß ein Druckeremulator wie der Diablo-Treiber oder der FX–80-Emulator geladen werden!

Wenn für Ihren Drucker kein passender Treiber beiliegt, können Sie eine für einen ähnlichen Drucker nehmen und diese modifizieren. Laden Sie dazu eine .HEX-Datei in einen Texteditor. Sie sehen links in (fast) jeder Zeile ein Steuerbyte für jede Steuerzeichensequenz (z. B. “Fett ein” o. ä.; dieses braucht HyperText bzw. 1st-Word), rechts daneben Hexadezimalzahlen, die dem Drucker signalisieren, was zu tun ist (diese werden also zu passender Gelegenheit an den Drucker gesendet). Welche Steuerzeichen welchem Vorgang entsprechen, entnehmen Sie bitte Ihrem Druckerhandbuch oder fragen Sie Ihren Händler. Ändern Sie die entsprechenden Steuerzeichen ab und speichern Sie die .HEX-Datei erneut. Danach können Sie daraus mit dem mitgelieferten Konverterprogramm MAKE_CFG eine .CFG-Datei erzeugen.

HyperText benötigt folgende Steuerzeichensequenzen:

No. Name & Bedeutung
20 Vortext & Wird am Anfang ausgegeben
1F Vorzeile & Wird vor jeder Zeile ausgegeben
1 Nachzeile & Normalerweise Cr/Lf
21 Nachtext & Wird zum Schluß ausgegeben
6 Bold & Fettschrift einschalten
7 No Bold & Fettschrift ausschalten
E Light & Helle Schrift einschalten
F No Light & Helle Schrift ausschalten
A Italics & Kursivschrift einschalten
B No Italics & Kursivschrift ausschalten
1A Underline & Unterstreichung einschalten
1B No Underline & Unterstreichung ausschalten
2A Elite & Outline ein = Elite
28 Pica & Outline aus = Pica

2.7 Die Bill-Buttons

Neben der oberen Buttonleiste kann auch am unteren Rand eine Reihe von Buttons erscheinen. Darin stehen Stichwörter von verwandten Kapiteln oder anderen wichtigen Abschnitten. Klicken Sie einfach auf einen dieser Buttons; Sie springen damit zu der entsprechenden Seite, als ob das Stichwort (fett) im laufenden Text gestanden hätte.

Erstellung von HyperText-Dokumenten

Dieser Abschnitt ist nur für Entwickler von Hilfstexten für HyperText gedacht; im Gegensatz zu dem vorigen Teil sollte er auch nur diesen zugänglich gemacht werden, wenn man HyperText in eigenen Programmen erklärt und obigen Text teilweise oder komplett in die Anleitung zum eigenen Programm übernimmt. Wichtig: Wer HyperText in eigenen Programmen verwendet, muß den Standard- About-Dialog von ∑-Soft unterstützen!

3.1 Das Diskettenformat

Die Hilfstext-Dateien von HyperText haben ein eigenes Format; diese Dateien tragen die Extension .HYP. Die Datei besteht aus drei Teilen:

  1. Einem Header mit Dateikennung und Versionsnummer
  2. Einem Datenteil, in dem alle Seiten u. ä. gespeichert sind; dieser Teil ist codiert
  3. Einem Directory, das auf die einzelnen Datenteile zeigt.

Dieses bedeutet runtimemäßig folgendes:

Der Header und das Directory werden ständig im Speicher gehalten. Zur Speicherplatzabschätzung: Eine Seite belegt momentan 12 Bytes im Directory. Der Header ist nur ein paar Bytes lang.

3.2 Die Speicherverwaltung

HyperText beinhaltet eine eigene Speicherverwaltung, die nicht Pointer auf Speicherblöcke verwaltet, sondern Handles (Pointer auf Pointer). Sie kann deshalb, im Gegensatz zu der des TOS, die Speicherblöcke frei verschieben und auch nachträglich vergrößern. HyperText holt nur beim Start einmal mit Malloc einen Speicherblock (entsprechend des Einstellungsmenüs), den es nie wieder freigibt. Dieser wird von der eigenen Speicherverwaltung zerteilt, um einzelne Seiten möglichst optimal buffern zu können.

Alle Seiten werden bei Bedarf in den Speicher geladen und erst bei Speicherplatzmangel wieder gelöscht. Die Seiten werden gepackt im RAM gehalten und nur die aktuelle wird entpackt. Bei jedem Aufruf einer Seite wird ein interner Zähler, die “Seitenwichtigkeit”, erhöht. Dadurch wird erreicht, daß die Seiten, die am häufigsten benötigt werden, zuletzt gelöscht werden. Sie können für “Knotenpunkte”, also Seiten, über die viel hinweggeblättert wird, diesen Zähler schon mit einem Wert vorbelegen (siehe unten).

Die Stichwörter sind in einer Art Delta-Compression abgelegt und belegen ein eigenes Segment (stehen also nicht im Directory). Dieses wird nur bei der Stichwortsuche oder bei einem Aufruf von HyperText per Protokoll geladen. Ein Stichwort-Segment selbst bei längeren Texten i.d.R. nur wenige KB lang.

Durch dieses Speicherverwaltungskonzept haben wir erreicht, daß HyperText schon auf sehr kleinen Rechnern läuft (bei nicht übergroßen Texten schon ab 512KB), aber auf größeren Rechnern sinnvoll seine Daten im RAM halten kann.

Anmerkung für TT-Besitzer: Da der Speicher mit Malloc geholt wird, können Sie über die Flags entscheiden, auf welches RAM sich der Einstellungsbereich bezieht. Wenn Sie HyperText hauptsächlich als Programm starten (wo immer 100% angenommen wird), haben Sie am meisten Speicher, wenn Sie beispielsweise das Programm ins ST- und den Buffer in Fast-RAM legen.

Wenn in HyperText eine Weile nicht geblättert wird, wird eine Speicher- reorganisation durchgeführt. Deshalb könnte es in ungünstigen Fällen zu einer Verzögerung führen, wenn große Speicherbereiche zu verschieben sind, auf einem 4MB-Rechner haben wir jedoch noch keine störenden “Aussetzer” bemerkt. Da ein Benutzer typischerweise sowieso mehrere Sekunden zum Lesen einer Seite benötigt, dürfte dieses aber keine Probleme bereiten. Sie können die Reorganisation beobachten, wenn Sie HyperText nur einen kleinen Speicher zubilligen und kontinuierlich blättern; alle paar Seiten stockt es kurz (das ist dann die Reorganisation).

Außerdem gibt es noch eine Blätterverzögerung nach der ersten Seite (nur auf schnellen Rechnern, beim alten ST fällt’s nicht auf), damit man eine einzelne Seite bei schnellen Rechner treffen kann.

3.3 Der Konverter

Wie erstellt man nun einen eigenen Hilfetext?

Zuerst einmal braucht man einen reinen ASCII-Text, in dem alle Seiten hintereinanderweg geschrieben sind. Dann lädt man das ganze in 1st-Word+ und versieht es mit Attributen. Sie können wie gewohnt alle Textattribute verwenden, nur von der Benutzung der Fettschrift wird dringend abgeraten, weil dieses nachher nicht von den Stichwörtern auseinanderzuhalten ist.

Dann sind alle Seiten durch feste Seitenumbrüche zu trennen. Die von 1st-Word+ automatisch eingefügten dynamischen werden vom Konverter ignoriert.

Zusätzlich müssen noch besondere Markierungen enthalten sein:

3.3.1 Die Steuerzeichen für den Konverter

Alle Stichwortdefinitionen müssen von Klammeraffen umschlossen werden. Also, wenn Sie ein Stichwort auf einer Seite erklären, dann schreiben Sie ein @ davor und dahinter. Alle Stichwortreferenzen werden vom Konverter automatisch erkannt und markiert. Achten Sie deshalb darauf, daß Sie nicht unsinnig kurze Stichwörter verwenden; z. B. die Sprache “C”, weil dann alle großen C in Ihrem Text markiert werden.

Nach einer Stichwortdefinition können noch mehrere Bill-Button-Einträge stehen, die durch Komma getrennt werden. Die Bill-Button erscheinen dann auf der Seite, wo das betreffende Stichwort erklärt ist. Beispiel: @Bconin,BIOS,XBIOS@ Wenn der angegebene Eintrag nicht existiert, wird kein Bill-Button generiert.

Es gibt noch optionale Befehle:

Befehl Beschreibung
#memo legt die Voreinstellung für die Speicherbelegung fest. Dahinter
folgt eine Zahl von 0 bis 1000, die die Belegung in Promille angibt.
#impo legt die Wichtigkeit einer Seite fest (wie im Abschnitt über
Speicherverwaltung beschrieben). Danach folgt ein Wert von 0 bis 255,
wobei 0 eine unwichtige Seite (default) und 255 eine sehr wichtige ist.
#imde Ändert die Defaultwichtigkeit. Sie können also vor einer Reihe von
“Menüseiten” die Defaulteinstellung auf beispielsweise 50 hochsetzen und
hinterher mit #imde 0 zurückstellen.

3.3.2 Arbeiten mit dem Konverter

Nach Erstellung des Textes startet man den Konverter und wählt im File-Selector das zu konvertierende 1st Word+ Dokument aus. Dieses wird nun in 3 Passes nach Stichworten durchsucht und gepackt. Der Konverter schafft auf einem Mega STE etwa 100 Seiten pro Minute zu übersetzen, auf dem TT ist er entsprechend schneller. Nach dem 2 Pass kann man im File-Selector die Zieldatei anwählen unter der die gepackten abgelegt werden. Die Extension sollte HYP sein. Momentan lädt HyperText nur die Datei HYPER.HYP. Dies kann sich jedoch später noch ändern.

Wenn man ein 1st Word+ Dokument direkt auf den Konverter zieht, dann wird das Dokument ohne weiteren File-Selector übersetzt.

Mit der rechten Maustaste kann man eine Konvertierung jederzeit abbrechen.

Weitere Möglichkeiten des Konverters:

  • Durch Ändern der Datei DEFAULT.RSC ist man in der Lage einen eigenen “About”-Dialog unter dem Atari-Symbol einzubinden. Der Button zum Aufruf der ∑-Soft-Dialogbox darf dabei NICHT entfernt werden!
  • Mit Hilfe der Datei DEFAULT.TXT kann man die Packrate weiter verbessern, in diese Datei schreibt man möglichst viele Wörter (maximal etwa 4KB) ohne Leerzeichen hintereinander weg. Man sollte nur Wörter verwenden, die auf möglichst vielen Seiten vorkommen und die länger als 3 Zeichen sind. Da HyperText natürlich nur seitenweise packen kann, kann man die Packrate dadurch erhöhen, indem man lange Wörter, die auf vielen Seiten vorkommen (Beispiel: “HyperText”, “Atari” o.ä.) durch den Konverter einmal packen läßt und sodaß diese Worte bereits gepackt in die Seiten eingetragen werden. Diese gepackten Wörter kosten natürlich zusätzlich Speicher (i.d.R. weniger als 4K, da die Datei gepackt im RAM gehalten wird), der ständig durch HyperText belegt bleibt. Wir haben in einem Fall z.B. eine HYPER.HYP ohne DEFAULT.TXT von über 800KB auf 620KB reduzieren können. Dies war bedingt dadurch, daß die vielen Seiten (über 1700) wenig Worte enthielten, jedoch sehr lange, die auf fast allen Seiten vorkamen (Die Rede ist vom Atari Softwareführer, der mit HyperText realisiert wurde).

3.4 “Unsauberkeiten” von HyperText

In HyperText werden drei undokumentierte Features des TOS benutzt, da uns noch nicht eingefallen ist, wie man dieses anders machen könnte. Alle Features sind jedoch relativ sauber, soll heißen: sie funktionieren auf allen uns bekannten TOS-Versionen (ST, STE und TT). Wir haben wegen dieser drei Punkte bei Atari angefragt und uns wurde bestätigt, daß diese drei Punkte akzeptabel sind.

  • In der Hauptschleife fragt HyperText mit einem evnt_multi beide Maustasten ab. (256 auf die Flags addiert)
  • Wenn HyperText als Accessory gestartet wird, ändert es act_pd, da der Malloc noch nicht unmittelbar nach dem Start erfolgt (sondern erst nach dem Einlesen des Dateiheaders, in dem ja die Speicherwunschgröße steht), und ein Accessory ja bekanntlich hinterher keinen Speicher mehr holen darf. Auch mit der später geöffneten Datei gibt’s sonst Probleme.

Wenn dies später zu Konflikten bei einem Multitasking-TOS führt, kann man HyperText ja als Programm starten, Accessorys sollten da eh ihre Bedeutung verlieren. (Wenn jemand Abhilfe weiß, dann bitte melden!)

  • Wenn HyperText auf das Turbo-C-Protokoll reagieren soll, ändert es seinen Namen mit einem menu_register(–1) (natürlich nur als Accessory). Dieses ist nötig, weil das aufrufende Programm das Accessory nur an seinem Namen erkennen kann. Ist zwar nicht schön, aber das Protokoll läßt leider nichts anderes zu. Da durch das “neue” Pure-C, daß Turbo-C-Help-Accessory auf Pure-C-Help umgetauft wurde, was bewirkt, daß z.B. Tempus das Pure-C- Accessory nicht mehr findet, könnte es in Zukunft Probleme geben, wenn Programme auf den Markt kommen, die nicht Turbo-C-Help, sondern Pure-C-Help unterstützen. Wir werden dann wohl noch eine zusätzliche Option einbauen: “Pure-C-Protokoll”. Bis dahin wollen wir die User nicht mit noch mehr Optionen belasten.

Wer das Turbo-C-Protokoll ausschaltet und auf XAcc umschaltet, umgeht diese Unsauberheit (falls es doch irgendwann mal zu Problemen führt), hat dann aber nicht die Möglichkeit z.B. von Tempus aus HyperText aufzurufen.

3.5 Programmierung von HyperText

Weil ich immer wieder danach gefragt werde:

HyperText ist komplett in Assembler geschrieben (natürlich mit dem TurboAss). Es ist nur etwa 9000 Zeilen lang und der Programmcode ist etwa 17KB lang. Dazu kommen noch 7KB Daten (Resourcen der Dialoge) und 7KB BSS-Segment. HyperText alloziert beim Laden einen Speicherblock, der als Buffer für die Seiten, das Directory der Datei, etc. dient. Der Speicher wird völlig dynamisch verwaltet.

Der Konverter ist nur etwa 3000 Zeilen lang, auch in Assembler geschrieben und der Programmcode ist nicht einmal 5KB lang. Dazu kommt noch 1KB Data- Segment (Resource vom Dialog). Er benötigt jedoch SEHR VIEL Speicher! Wer nur 512KB hat, kann den Konverter nichtmal starten. Ich habe ihn zwar so aufgebaut, daß er möglichst wenig Daten im RAM hält, sodaß er auch Dokumente von einigen MB übersetzen kann (so denn 1st Word+ diese erzeugen kann :-), aber er benötigt eine statische Struktur für das Directory und die (noch) ungepackten Stichwörter.

Wer noch Ideen für HyperText hat, schicke sie bitte an die Adresse von ∑-Soft.

Markus Fritze, ∑-Soft