home *** CD-ROM | disk | FTP | other *** search
-
- Text-Aufbau
- ===========
-
- Diese Datei beschreibt den Aufbau eines Textes in HotHelps internem
- Text-Format. Kenntnisse über dieses Format sind nur notwendig, wenn über
- einen Handler oder die Library-Funktion 'HH_ASyncCustomText ()' ein Text
- in einem HotHelp-Fenster dargestellt werden soll, der nicht in einer
- Projekt-Datei vorliegt. Ein solcher Text muß - wenn er an HotHelp
- übergeben wird - in HotHelps internem Text-Format vorliegen.
-
- Im Normalfall kann dazu ein ganz normaler ASCII-Text verwendet werden,
- der dann mit Hilfe der Funktion 'HH_Translate ()' in das HotHelp-Format
- umgesetzt werden kann. Nur wenn diese Möglichkeit nicht genutzt werden
- soll (weil eine 100%ige Kontrolle über den Aufbau des Textes notwendig
- ist), sollte der Text direkt in HotHelps internem Format aufgebaut werden.
-
- Das HotHelp-Format setzt sich zusammen aus dem normalen Text (der
- später im Fenster ausgegeben wird) und einer Reihe von Steuercodes, die
- als Binär-Zahlen im Text eingestreut werden. Im Augenblick sind nur Codes
- mit Werten zwischen 0 und 8 in Verwendung. Im Hinblick auf Kompatibilität
- mit zukünftigen Versionen sollten aber grundsätzlich keine Binärwerte
- kleiner 20 verwendet werden (mit Ausnahme von 'Tab' und 'Return'
- natürlich). Sinnvoll wären solche Codes sowieso nicht, da sie von der
- 'Text ()'-Routine nicht vernünftig ausgegeben werden können.
-
- Während HotHelp bei Verwendung von 'HH_Translate ()' den zu
- übersetzenden Quelltext auf mögliche Fehler hin untersucht, wird ein Text,
- der in HotHelps internem Format vorliegt, keiner weiteren Untersuchung
- mehr unterzogen - HotHelp geht davon aus, daß der Text aus zuverlässiger
- Quelle stammt ('HH_Translate ()', HotHelpComp) und verläßt sich auf seine
- Integrität. Die fehlerhafte Definition eines solchen Textes kann dann
- beliebig katastrophale Folgen haben!
-
-
- Textende
- ========
-
- Als letztes Zeichen des Textes muß unbedingt der Ende-Code '\x00'
- angegeben werden.
-
-
- Absätze
- =======
-
- Die kleinste Einheit, in die Texte eingeteilt werden können, sind
- Absätze. Die Aufteilung in Zeilen wird erst später bei der Ausgabe
- vorgenommen und richtet sich nach der dann aktuellen Fenster-Breite. Der
- gesamte Text eines Absatzes muß also in einer einzigen Zeile abgelegt
- werden. Erst am Ende dieser überlangen Zeile darf dann der
- Zeilenvorschub-Code '\n' verwendet werden, der von HotHelp als
- Absatzende-Code verwendet wird. Um hinter einem Absatz ein oder mehrere
- Leerzeilen einzufügen, werden entsprechend viele weitere '\n'-Codes
- eingesetzt.
-
- Hier ein Beispiel für die Aufteilung eines Textes in Absätze. Würde
- der folgende String an HotHelp zur Darstellung übermittelt, würde die
- darauf folgende Ausgabe erzeugt (der Rahmen repräsentiert das
- HotHelp-Fenster):
-
- "Dies ist ein kleiner Beispiel-Text.\nabcdefgh\n\nijklmnopq\n\x00"
-
- +-----------------+
- |Dies ist ein |
- |kleiner Beispiel-|
- |Text. |
- |abcdefgh |
- | |
- |ijklmnopq |
- +-----------------+
-
- Obwohl in Zeile 3 noch genug Platz wäre, um den Text 'abcdefgh'
- aufzunehmen, wird dieser in einer neuen Zeile ausgegeben, da hinter
- 'Text.' ein Absatzende definiert wurde. Die folgende Leerzeile wird durch
- die beiden aufeinanderfolgenden '\n's erzeugt. Am Textende könnte auch
- auf den Zeilenvorschub verzichtet werden.
-
-
- Einrückungen
- ============
-
- Für jeden Absatz können zwei Einrückungs-Tiefen vorgegeben werden: die
- Tiefe der ersten ausgegebenen Zeile und die Tiefe aller folgenden Zeilen.
- Im Normalfall wird keine Zeile eingerückt; eine Einrückung muß durch eine
- eigene Marke angefordert werden. Es darf nicht versucht werden,
- Einrückungen durch Einfügen von Blanks oder Tabulatoren zu erzeugen: am
- Anfang eines Absatzes werden diese übersprungen und befinden sie sich
- innerhalb eines Absatzes, so können sie bei verschiedenen Fensterbreiten
- auch an ganz verschiedenen Positionen innerhalb der Zeilen auftauchen -
- selten jedoch genau am Zeilenanfang!
-
- Um für einen Absatz eine bestimmte Einrückungs-Tiefe zu bestimmen, muß
- das ERSTE Zeichen des Absatzes der Code '\x03' sein. Das folgende Byte
- gibt dann die Einrückungstiefe für die erste Zeile des Absatzes an, das
- nächste Byte die Tiefe für alle weiteren Zeilen. Es können Werte zwischen
- 0 (keine Einrückung) und 127 (paßt auf keinen normalen Bildschirm mehr)
- angegeben werden. Der Code darf nur unmittelbar am Anfang eines Absatzes
- und sonst nirgendwo verwendet werden.
-
- Dazu wieder ein Beispiel. Die erste Zeile des zweiten Absatzes wird um
- 8 Schritte eingerückt, alle weiteren Zeilen um 4. Andere als der zweite
- Absatz werden davon nicht betroffen - wird keine Einrückung angefordert,
- werden die Zeilen auch nicht eingerückt.
-
- "BlaBla.\n\x03\x08\x04Quassel Quassel Bläh Blubber\nTest Test\x00"
-
- +-----------------+
- |BlaBla. |
- | Quassel |
- | Quassel Bläh |
- | Blubber |
- |Test Test |
- +-----------------+
-
-
- Querverweise
- ============
-
- Soll ein Teil eines Textes als Querverweis definiert werden, so muß er
- durch den Querverweis-Codes eingerahmt werden. Vor dem ersten Zeichen des
- Querverweises muß in jedem Fall der Code '\x01' eingefügt werden. Stößt
- HotHelp bei der Ausgabe auf diesen Wert, so wird der folgende Text farbig
- hervorgehoben. Das Ende des Querverweises kann nun auf verschiedenen
- Wegen angezeigt werden:
-
- Um einen ganz normalen Querverweis zu definieren, wird hinter dem
- Querverweis-Text der Code '\x02' eingefügt.
-
- Soll ein Querverweis mit zusätzlicher Projekt-Angabe erzeugt werden,
- müssen hinter dem Querverweis-Text selber die folgenden Codes eingefügt
- werden: '\x08', '??', '\x06' und '\xFF'. Direkt danach muß dann der Name
- des gewünschten Projektes eingefügt werden. Dieser String darf nicht
- 0-terminiert sein und hat eine Maximallänge von 'HH_PROJECT_LEN - 1'. Die
- Länge dieses Strings muß (um vier erhöht) anstelle des oben mit '??'
- markierten Bytes in den Text eingefügt werden.
-
- Um einem Querverweis ein ARexx-Kommando zuzuordnen, wird prinzipiell
- genauso vorgegangen wie beim Projekt-Querverweis. Die Codefolge, die
- hinter dem Querverweis eingefügt werden muß, lautet jetzt jedoch '\x08',
- '??', '\x07' und '\xFF'. Als nächstes muß dann der String mit dem
- ARexx-Befehl eingefügt werden, der ebenfalls nicht 0-terminiert sein darf
- und eine Maximallänge von 'HH_AREXX_LEN - 1' Bytes haben darf. Anstelle
- von '??' muß auch hier die Länge des Strings + 4 eingesetzt werden.
-
- Taucht in einem ARexx-Kommando das Zeichen '|' auf, verwendet HotHelp
- den Text vor dem Zeichen als Host-Name, die Zeichen dahinter als
- eigentliches Kommando. Taucht das Zeichen nicht auf, wird der gesamte
- String an den ARexx-Host übermittelt.
-
- Der Querverweis selber darf niemals länger als 'HH_KEY_LEN - 1' Bytes
- sein - längere Verweise führen spätestens bei der Auswahl durch den
- Benutzer zum Überlauf eines internen Puffers!
-
- Die folgenden Texte definieren - umrahmt von normalen Text, der hier
- durch Punkte symbolisiert wird - einen normalen Querverweis, einen
- Projekt-Querverweis und einen ARexx-Querverweis:
-
- "...\x01Normaler Querverweis\x02..."
- "...\x01Projekt-Querverweis\x08\x10\x06\xFFProjekt-Name..."
- "...\x01ARexx-Querverweis\x08\x12\x07\xFFARexx-Kommando...\x00"
-
- In Zeile 2 und 3 sind die erweiterten Texte ('Projekt-Name' und
- 'ARexx-Kommando') nicht vom folgenden normalen Text abgetrennt. Dies ist
- auch nicht notwendig, da HotHelp bei der Ausgabe hinter der abschließenden
- Marke einfach soviele Bytes überspringt, wie das entsprechende Längen-Byte
- angibt.
-
-
- Schriftarten
- ============
-
- Um eine bestimmte Schriftart anzuforden, wird der Code '\x04'
- verwendet. Im darauffolgenden Byte wird dann ein Code für die geforderte
- Schriftart selber abgelegt. Hierfür sind nur Werte zwischen 0 und 7
- erlaubt:
-
- 0: Normal
- 1: Unterstrichen
- 2: Fett
- 3: Fett + Unterstrichen
- 4: Kursiv
- 5: Kursiv + Unterstrichen
- 6: Fett + Kursiv
- 7: Fett + Kursiv + Unterstrichen
-
- Die Schriftart wird beibehalten, bis der aktuelle Absatz beendet ist
- oder bis durch eine weitere Schriftart-Marke eine andere Schriftart
- angefordert wird.
-
- Das Beispiel gibt einen unterstrichenen Text, einen normalen, einen mit
- allen drei möglichen Schriftarten versehenen und einen fetten Text aus.
- Am Absatzende wird dann automatisch wieder auf Normal-Text umgeschaltet,
- so daß ein noch folgender Absatz wieder normal ausgegeben würde.
-
- "\x04\x01Unterstrichen\x04\x00Normal\x04\x07Alle Styles\x04\x04Fett\n"
-
-
- Fließtext
- =========
-
- Normalerweise wird aller Text von HotHelp als Fließtext behandelt;
- d.h., daß der Text bei der Ausgabe anhand der aktuellen Fenster-Breite und
- der Breite des verwendeten Zeichensatzes formatiert wird. Ist dies nicht
- gewünscht, kann über eine Kennung festgelegt werden, daß die folgenden
- Zeilen nicht umgebrochen werden sollen; falls eine Zeile zu breit für das
- Fenster wird, kann der Fensterinhalt über die drei Gadgets am unteren
- Fensterrand gescrollt werden.
-
- Die Fließtext-Marke wirkt dabei als Umschalter: bei ihrem ersten
- Auftreten schaltet sie die Fließtext-Darstellung aus, so daß die
- Folgezeilen als Nicht-Fließtext betrachtet werden; das nächste Auftreten
- schaltet den Fließtext dann wieder ein etc. Die folgenden Zeichen müssen
- in den Text eingefügt werden, um die Darstellung umzuschalten: '\x08',
- '\x03' und '\x09'.
-
-
- AmigaGuide-Querverweis
- ======================
-
- Um die Darstellung von AmigaGuide-Texten zu ermöglichen, wurde diese
- neue Marke eingeführt. Sie kann nicht über HotHelpComp erzeugt werden,
- sondern wird lediglich intern verwendet. Die Marke wird ebenso benutzt
- wie die übrigen Querverweis-Marken, mit dem Unterschied, daß das
- Querverweis-Ende jetzt durch die Codes '\x08', '??', '\x08' und '\xFF'
- dargestellt wird - alles andere bleibt gleich (Einleiten mit '\x01', nach
- den Ende-Code folgt der nicht 0-terminierte Folgestring, dessen Länge + 4
- anstelle von '??' abgelegt werden muß).
-
- Der Folgestring hat es aber nun in sich. Enthält er weder ein ':' noch
- ein '/', wird er als ganz normaler Schlüssel-Begriff angesehen, der mit
- diesem Querverweis verknüpft ist. Gegenüber normalen Querverweisen können
- sich hier also der sichtbare Teil (der im Fenster hervorgehoben und
- ausgewählt werden kann) und der zu dem Verweis gehörende Schlüssel
- unterscheiden (wie dies beim AmigaGuide üblich ist).
-
- Enthält der String einen ':' oder mindestens zwei '/', wird er als
- Dateiname angesehen. HotHelp lädt dann die entsprechende Datei nach.
- Enthält der Dateiname keinen ':', wird ab OS 2.0 der Pfadname relativ zum
- Inhalt der Umgebungs-Variablen 'AmigaGuide/Path' ausgewertet. Die Ausgabe
- beginnt normalerweise mit der ersten Zeile des Textes; soll die
- Darstellung mit einer anderen Zeile beginnen, muß deren Nummer (von 0 an
- gezählt) durch ein Semikolon getrennt am Ende des Strings angegeben
- werden. HotHelp ignoriert - von dieser Zahl abgesehen - alle Zeichen
- hinter dem letzten '/'-Zeichen des Strings.
-
- Enthält der String nur einen einzigen '/' und stellt der Teilstring
- davor den Namen eines Projektes dar, wird der Begriff als ein
- Projekt-Querverweis aufgefaßt - andernfalls wird er ebenfalls als
- Dateiname behandelt.
-
- Wie üblich dürfen die Querverweise nicht länger als 'HH_KEY_LEN - 1'
- Bytes sein. Hier einige Beispiele:
-
- "...\x01Normaler Querverweis\x08\x0A\x08\xFFNormal..."
- "...\x01Projekt-Querverweis\x08\x11\x08\xFFGlossar/ASCII..."
- "...\x01Datei-Querverweis\x08\x18\x08\xFFWork:Datei-Name/Main..."
- "...\x01Datei-Querverweis\x08\x18\x08\xFFTexte/Hilfe/Main;123...\x00"
-
- In Fall 1 wird bei der Ausgabe der Text 'Normaler Querverweis'
- angezeigt, der über Maus oder Tastatur ausgewählt werden kann. Der
- zugehörige String ("Normal") enthält weder '/' noch ':', so daß er als
- ganz normaler Schlüssel-Begriff behandelt wird. Bei Fall 2 wird
- 'Projekt-Querverweis' angezeigt. Der zugeordnete String enthält lediglich
- einen '/' und deutet so an, daß der Schlüssel 'ASCII' aus dem
- 'Glossar'-Projekt gemeint ist.
-
- Beispiel 3 und 4 werden beide als 'Datei-Querverweis' angezeigt. Der
- String des dritten Querverweises enthält einen Doppelpunkt, so daß es sich
- offensichtlich um einen Dateinamen handelt. Geladen wird die Datei
- 'Work:Datei-Name' - der Schlüssel-Begriff 'Main' am Ende wird ignoriert.
- Der letzte Querverweis bezieht sich ebenfalls auf eine Datei, da mehr als
- ein '/' auftaucht. Der Name wird relativ zur Umgebungs-Variablen
- 'AmigaGuide/Path' ausgewertet und bezieht sich auf eine Datei namens
- 'Hilfe' im Verzeichnis 'Texte'. Die Datei wird ab Zeile 123 dargestellt.
-
-
- Kapitel
- =======
-
- Diese Marke ermöglicht es (neben der Verwendung von Gruppen-Titeln),
- einem Text einen weiteren Text als Kapitel-Übersicht zuzuordnen. Dazu
- wird dem Eintrag mit Hilfe dieser Marke ein Schlüssel-Begriff zugeordnet;
- betätigt der Benutzer dann das Kapitel-Gadget, wird der zu diesem
- Schlüssel gehörende Eintrag angezeigt. Der so definierte
- Kapitel-Querverweis wird bei der Ausgabe unterdrückt.
-
- Um einen solchen Kapitel-Namen zu vergeben, muß die Code-Folge '\x08',
- '??', '\x00', '\FF' in den Text eingefügt werden. Unmittelbar dahinter
- folgt dann der Schlüssel-Begriff selber (nicht '\0'-terminiert). Er darf
- maximal 'HH_KEY_LEN - 1' Zeichen lang sein. Er wird ebenso ausgewertet
- wie der Schlüssel-Begriff eines AmigaGuide-Querverweises. Die Länge des
- Strings + 4 muß anstelle von '??' eingesetzt werden.
-
- "...\x08\x15\x00\xFFKapitel-Übersicht..."
-
- Dieses Beispiel definiert 'Kapitel-Übersicht' als String, der bei
- Auswahl des Kapitel-Gadgets als neuer Suchschlüssel verwendet wird.
-
-
- Vorgängertext, Nachfolgertext
- =============================
-
- Ähnlich wie bei der Kapitel-Angabe können über diese Marken Schlüssel
- angegeben werden, die bei Auswahl des Pfeil-links- (<) bzw. Pfeil-rechts-
- (>) Gadgets verwendet werden sollen. Dazu wird genauso vorgegangen wie
- bei der Definition des Kapitel-Schlüssels; für den Vorgängertext muß
- lediglich anstelle des '\x00'-Bytes der Wert '\x02', für den
- Nachfolgertext der Wert '\x04' eingesetzt werden.
-
- "...\x08\x0B\x02\xFFVortext..."
- "...\x08\x0D\x04\xFFFolgetext..."
-
- Beispiel 1 belegt das '<'-Gadget mit dem Schlüssel 'Vortext', Beispiel
- 2 versieht das '>'-Gadget mit dem Schlüssel 'Folgetext'.
-
-
- Farbe
- =====
-
- Über diese Marke kann die Vorder- und Hintergrundfarbe des Textes
- geändert werden. Dazu werden die folgenden Codes in den Text eingefügt:
- '\x08', '\x04', '\x0A' und '??'. Anstelle von '??' muß ein Code für die
- gewünschten Farben eingesetzt werden. Die oberen vier Bit werden für die
- Hintergrund-, die unteren 4 Bit für die Vordergrund-Farbe verwendet. Es
- können jeweils die folgenden 9 Werte eingesetzt werden, die den Indizes in
- das Feld 'dri_Pens' der DrawInfo-Struktur entsprechen (zum Setzen der
- Hintergrundfarbe muß der entsprechende Wert um 4 Bits nach links
- verschoben werden; also z.B. zum Setzen des FILLPENS '\x05' für die
- Vordergrundfarbe und '\x50' für die Hintergrundfarbe):
-
- 0 - DETAILPEN
- 1 - BLOCKPEN
- 2 - TEXTPEN
- 3 - SHINEPEN
- 4 - SHADOWPEN
- 5 - FILLPEN
- 6 - FILLTEXTPEN
- 7 - BACKGROUNDPEN
- 8 - HIGHLIGHTTEXTPEN
-
- Soll die entsprechende Farbe unverändert bleiben, muß der Wert '\x0F'
- (bzw. '\xF0' für die Hintergrundfarbe) eingesetzt werden.
-
- "...\x08\x04\x0A\x13..."
- "...\x08\x04\x0A\xF2..."
-
- Das erste Beispiel setzt die Vordergrundfarbe auf SHINEPEN und die
- Hintergrundfarbe auf BLOCKPEN. Im zweiten Beispiel wird die
- Hintergrundfarbe unverändert beibehalten, während die Vordergrundfarbe auf
- den TEXTPEN gesetzt wird.
-
-
- Gruppen-Listen, Gruppen-Titel und Gruppen-Querverweise
- ======================================================
-
- Die Verwendung dieser Objekte ist nicht möglich, da Gruppen eindeutig
- einem Projekt zugeordnet sein müssen. Wird aber ein Text an HotHelp über
- einen Handler oder 'HH_ASyncCustomText ()' übermittelt, gehört dieser
- logischerweise keinem Projekt an, so daß er auch keine Gruppen-Listen
- verwenden darf.
-
-
- Übersicht
- =========
-
- Textende: \x00
- Start Querverweis: \x01
- Ende Querverweis: \x02
- Einrückung: \x03 i1 i2
- Schriftart: \x04 s
- Ende Projekt-Querverweis: \x08 l \x06 \xFF str
- Ende ARexx-Querverweis: \x08 l \x07 \xFF str
- Ende AmigaGuide-Querverweis: \x08 l \x08 \xFF str
- Fließtext-Toggle: \x08 \x03 \x09
- Kapitel: \x08 l \x00 \xFF str
- Vorgängertext: \x08 l \x02 \xFF str
- Nachfolgertext: \x08 l \x04 \xFF str
- Farbe: \x08 \x04 \x0A f
- Tabulator: \t
- Absatzende: \n
-
- i1, i2: Zwei Bytes mit den Einrückungs-Tiefen.
- s: Ein Byte mit dem Code der gewünschten Schriftart.
- l: Ein vorzeichenloses Byte mit der Länge des folgenden Strings
- 'str', erhöht um den Wert 4.
- str: Ein String der Länge 'l - 4', nicht '\0'-terminiert.
- f: Ein Byte, das die Vorder- und Hintergrundfarbe angibt.
-
- Die Codes '\x05' und '\x06' sind für die Verwendung von Gruppen
- reserviert und dürfen daher nicht angegeben werden (siehe oben).
- Tabulatoren und Absatzenden werden mit den üblichen Zeichen definiert.
-