initial commit
This commit is contained in:
root
295
tools/hyp_view/doc/hypdoc.txt
Normal file
295
tools/hyp_view/doc/hypdoc.txt
Normal file
@@ -0,0 +1,295 @@
|
||||
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:
|
||||
<name>/<node-name>
|
||||
|
||||
-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
|
||||
|
||||
Reference in New Issue
Block a user