ST-Guide Hypertext Format (=HYP) ========================= Dies ist eine Dokumentation des ST-Guide Hypertext Formats. Sie basiert auf der Dokumentation, die man im HCP Hypertext von Holger Weets findet. Dazu habe ich an einigen Stellen Ergaenzungen angebracht, welche mir beim Programmieren meines Hypertext Viewers aufgefallen sind. Meine Ergaenzungen sind mit [PhD] gekennzeichnet. Diese Dokumentation bitte nicht weitergeben! Philipp Donze Chavornay, 05.05.2002 ================================== schnipp ================================ Header eines Hypertextes ------------------------ Der Header einer Hypertext Datei ist wie folgt aufgebaut: 4 Bytes Magic ('HDOC') 4 Bytes Laenge der Indextabelle (Seiten, Bilder, ext. Referenzen, system, rexx) 2 Bytes Anzahl der Eintraege in dieser Tabelle 1 Byte Kennung, mit welcher Version des Compilers uebersetzt wurde (aktuell 3) 1 Byte Kennung, unter welchem Betriebsystem uebersetzt wurde (0: unbekannt, 1: AMIGA, 2: ATARI, 3: Macintosh) Indexbereich eines Hypertextes ------------------------------ 1 Byte Laenge dieses Eintrages 1 Byte Typ dieses Eintrages 0: interne Seite (@node) 1: Popup-Node (@pnode) 2: externe Referenz (@{... link FILE [LINE]}) 3: Bild (@image) 4: SYSTEM-Argument (@{... system ARG}) 5: REXX-Script (@{... rxs FILE}) 6: REXX-Kommando (@{... rx ARG}) 7: QUIT Dummy-Eintrag (@{... quit}) 4 Bytes Seek Offset in die Datei 2 Bytes Differenz entpackte/gepackte Laenge des Objektes 2 Bytes Index des Nachfolgers 2 Bytes Index des Vorgaengers 2 Bytes Index des Inhaltsverzeichnisses fuer dieses Objekt x Bytes Name des Objektes, nullterminiert evtl. ein weiteres Nullbyte, damit der naechste Eintrag wieder auf einer geraden Adresse liegt Von diesen Strukturen finden sich so viele in der Datei, wie der entsprechende Wert im Header angibt. Die Laenge einer Seite berechnet sich aus der Differenz der Seek-Offsets dieser Seite und der des Nachfolger-Objektes. Erweiterte Header ----------------- Erweiterte Header dienen i.w. dem Zweck, alle Daten auch bei Er- weiterungen des Systems kompatibel zu aelteren Versionen zu halten. Der Aufbau eines solchen Headers ist wie folgt: 2 Bytes Kennung 2 Bytes Laenge n Bytes Daten Aktuell existieren folgende Header: 0 Ende-Kennung, es folgen keine weiteren Header mehr 1 Database Name, es folgen Laenge und C-String (@database) 2 Name der Default-Node, es folgen Laenge und C-String (@default) 3 Name der Host-Applikation(en), es folgen Laenge und C-String(s) (@hostname) 4 Optionen, die von den Default-Einstellungen abweichen, es folgen Laenge und C-String (@options, Kommandozeile) 5 Name des/der Autoren, es folgen Laenge und C-String (@author) 6 Versions-Information, es folgen Laenge und C-String (@$VER:) 7 Name der Hilfe Seite, es folgen Laenge und C-String (@help) 8 Beschreibung der Gebiete, in die der Text einzuordnen ist, es folgen Laenge und C-String (@subject) 9 HypTree-Header; Aufbau: 4 Bytes Summe der Laengen aller expliziten Titel Array von Wortbreiten Bitvektoren: 1. Wort: Bit n == 1 -> Seite n hat einen expliziten Titel 2. Wort: Bit n == 1 -> Seite 16+n hat einen expiziten Titel usw. 10 Flags fuer den ST-Guide (2 Bytes) Falls das Bit 10 gesetzt ist, so ist der Hypertext verschluesselt. [PhD] 11 verwendete Zeilenlaenge (@width) Ein Lesealgorithmus fuer diese Header muss alle ihm nicht bekannten Header ohne Warnung oder Fehlermeldung ueberlesen. Datenbereich eines Hypertextes ------------------------------ Alle Seiten, Popup's und Bilder, die im Hypertext definiert wurden. Meist liegen die Daten in gepackter Form vor, so dass sie nicht ohne weiteres verwendet werden koennen. Der verwendete Pack-Algorithmus entspricht dem LH5 Verfahren des LHarc, ist somit sehr effizient und zumindest beim Auspacken auch schnell genug. Die Reihenfolge der Daten-Objekte entspricht der der Indextabelle, externe Referenzen, system- und rexx-Eintraege besitzen keine Daten in diesem Bereich, die Daten gehoeren folglich immer zu einer * Textseite oder zu einem * Bild Format einer [p]node -------------------- Gehoeren die Daten zu einer Textseite (@node, @pnode), so haben die (entpackten) Daten folgendes Format: a) optionaler Grafikbereich (nur @node) Hier werden alle grafischen Objekte dieser Seite wie folgt beschrieben: 1 Byte Kennung (27, ESCAPE) 1 Byte Typ 50: Bild (@image) 51: Linie (@line) 52: Box (@box) 53: Box mit runden Ecken (@rbox) 2 Bytes Index, falls Bild damit keine 0-Bytes entstehen, liegt dieser Wert zur Basis 255 vor und zu beiden Bytes wurde der Wert 1 addiert 1 Byte X-Offset in Zeichen Bilder: falls X = 0 ==> zentriert [PhD] 2 Bytes Y-Offset in Zeichen damit keine 0-Bytes entstehen, liegt dieser Wert zur Basis 255 vor und zu beiden Bytes wurde der Wert 1 addiert 1 Byte Breite des Objektes in Zeichen Bilder: falls Breite = 1 ==> limage [PhD] 1 Byte Hoehe des Objektes in Zeichen 1 Byte Data, falls kein Bild Bevor folgende Aufschluesselung angewendet werden kann muss zuerst "Data" um eins verkleinert werden! [PhD] Linie: Bit 0 == 1: Pfeilspitze am Anfang Bit 1 == 1: Pfeilspitze am Ende restliche Bits: Linienstil Box: RBox: Fuellmuster Bei Bildern werden Breite und Hoehe ignoriert, bei Linien bilden sie das umgrenzende Rechteck. b) optional bis zu 12 Querverweis-Datenbloecke 1 Byte Kennung (27, ESCAPE) 1 Byte Typ (48) 1 Byte Laenge (ueber alles) 2 Bytes Indexnummer der Zielnode (im 255er Format [PhD]) Text fuer das Popup, Nullterminiert c) optional weitere Datenbloecke 1 Byte Kennung (27, ESCAPE) 1 Byte Typ (40-47) 1 Byte Laenge (ueber alles) Daten d) optional Fenstertitel (@node, @title) 1 Byte Kennung (27, ESCAPE) 1 Byte Typ (35) Fenstertitel, Nullterminiert evtl. Fuellbyte, damit der Text auf einer geraden Adr. beginnt e) optional Tabelle mit Objekten & Seiten (@tree) 1 Byte Kennung (27, ESCAPE) 1 Byte Typ (49, ObjTable) 2 Bytes Zeilennummer in der Zielseite 2 Bytes Nummer des Baumes 2 Bytes Objekt in diesem Baum 2 Bytes Index der Seite Damit keine 0-Bytes entstehen, liegen alle 2 Byte Werte zur Basis 255 vor und zu beiden Bytes wurde der Wert 1 addiert; f) optional Text mit Attributen Die einzelnen Zeilen sind durch ein 0-Byte abgeschlossen und koennen beliebig viele nicht auszugebende Zusatz-Information enthalten. Diese Informations-Sequenzen werden jeweils durch das Zeichen ESCAPE (27) eingeleitet, ihm folgt ein weiteres ESCAPE oder ein Typ, im ersten Fall ist das Zeichen ESCAPE auszugeben und im zweiten Fall bestimmt der Typ das weitere Vorgehen: 36: Referenz auf andere Seite @{... link NODE} 37: wie 36, aber mit Zeilennummer @{... link NODE LINE} 38: wie 36 nur durch 'alink' erzeugt @{... alink NODE} 39: wie 38, aber mit Zeilennummer @{... alink NODE LINE} >= 100: Vektor fuer Textattribute: nach Abzug von 100 ergibt sich folgender Bitvektor: 1: Fettschrift 2: helle Schrift 4: Kursivschrift 8: unterstrichen 16: 'Outlined' 32: schattierte Schrift Bei Typ 37 und 39 folgen 2 Bytes Zeilennummer; damit keine 0-Bytes entstehen, liegt dieser Wert zur Basis 255 vor und zu beiden Bytes wurde der Wert 1 addiert Bei Typ 36-39 folgen nun 2 Bytes Index in die Tabelle aus dem Indexbereich; damit keine 0-Bytes entstehen, liegt dieser Wert zur Basis 255 vor und zu beiden Bytes wurde der Wert 1 addiert 1 Byte Laenge des betreffenden Strings + 32 ist die Laenge gleich 32, so ist hier direkt der Name des indizierten Objektes auszugeben, ansonsten so viele Zeichen, wie die Laenge angibt, minus 32 aus der nachfolgenden Zeichenkette Format eines Bildes ------------------- Gehoeren die Daten zu einem Bild, so liegt (nach dem Entpacken) folgendes Format vor: a) Header 2 Bytes Breite des Bildes in Pixeln (wird ignoriert) 2 Bytes Hoehe des Bildes in Pixeln (wird ignoriert) 1 Byte Anzahl der Planes (1..8) 1 Byte 'Planepic': Bit n == 1 --> Daten fuer Plane n vorhanden 1 Byte 'PlaneOnOff': Bit n == 1 --> Plane ganz ausgefuellt 1 Byte Filler, damit das Bild auf gerader Adr. liegt b) 1. Plane optional 2. Plane ... optional 8. Plane Format einer REF Datei ---------------------- Datei-Kennung 4 Bytes Magic ('HREF') Modul-Header 4 Bytes Laenge des Moduls ohne Header 4 Bytes Anzahl der Eintraege im aktuellen Modul Modul-Daten 1 Byte Kennung des Eintrages 0: Dateiname (z.B. 'ST-GUIDE') immer ohne Pfad (eintragen eines Pfades ist jedoch erlaubt) und meist auch ohne Endung (als Endung wird .HYP verwendet, falls keine angegeben) 1: Node Name Seitenname aus dem Hypertext zum letzten Datei-Eintrag 2: Alias Name Aliasname aus dem Hypertext zum letzten Node-Eintrag (wird vom hcp nur optional hier eingetragen) 3: Label Name Labelname aus dem Hypertext zum letzten Node-Eintrag (wird vom hcp nur optional hier eingetragen) 4: database Name Database-Argument zum letzten Dateieintrag 5: Kennung des Betriebsystemes, unter dem der Hypertext uebersetzt wurde ('0': unbekannt, '1': AMIGA, '2': ATARI, '3': Macintosh) 1 Byte Laenge des Eintrages n Bytes Eintrag als Nullterminierter String bei Typ 3 folgen dem String noch 2 Bytes Zeilennummer Beliebig viele weitere Modul-Header gefolgt von Modul-Daten. 8 Bytes Nullen als Ende-Kennung [PhD] Diese 8 0-Bytes sind nicht in der Modul-Laenge enthalten! ====================== [PhD] ============================ Ab hier folgen meine eigenen Notizen: -Format einer externen Referenz (=Node Typ 2 bzw. @{... link FILE [LINE]}) Es gibt keine Daten zum Laden, daher ist im Index die Laenge 0. Saemtliche Daten befinden sich im Namen des Index-Eintrags und zwar im folgenden Format: / -Groessen-Angabe bei Bildern: Da Bilder groesser als 65KB sein koennen, die Angabe ueber die Laenge der entkomprimierten Daten aber auf 2 Bytes (=bis zu 65536 Bytes an Daten) beschraenkt ist, wird zur Berechnung der waren Groesse der Index-Eintrag "next" zu hilfe gezogen: entkomp. Groesse = komp. Groesse + (index->next<<16)+index->comp_diff