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
 
