Help! Help! Auf der TOS-Disk: Baukasten für Online-Hilfen

»Help! I need somebody« - wenn der Anwender Ihres Programms Hilfe braucht, unterstützen Sie ihn doch: mit »Help«, das jeder GEM-Software eine komfortable Hilfefunktion zur Seite stellt.

Jetzt fehlt noch eine Marke, die das Ende der Erklärung kennzeichnet. Schließlich wollen wir beim Begriff »Übersicht« nicht auch noch alles über das Leben, das Universum und den ganzen Rest sehen. Dafür sorgt die Marke ».«. Sie steht immer am Ende einer Erläuterung. Ein beliebter Fehler ist es, diese einfach zu vergessen. Am besten gewöhnen Sie es sich an, beim Schreiben hinter eine Erklärung immer gleich die Endemarke zu setzen. Wie die Kommentarmarke muß übrigens auch sie am Zeilenanfang stehen.

Der »Help«-Compiler

Mit dem beschriebenen Hilfe-Quelltext kann unser Accessory leider gar nichts anfangen. Es benötigt nämlich zwei Dateien: die Indexdatei und die Hilfetextdatei. Diese enthält im wesentlichen unseren Quelltext, allerdings in komprimierter Form (z.B. fallen die Kommentare weg). Die Indexdatei hingegen stellt eine Art Inhaltsverzeichnis dar. Sie enthält Informationen darüber, zu welchen Schlüsselwörtern Erklärungen existieren, und wo sie in der Hilfetextdatei zu finden sind. Den Aufbau der beiden Dateien brauchen Sie nicht zu kennen, da Sie nur den Quelltext schreiben müssen. Den Rest nimmt Ihnen der »Help«-Compiler ab, der sich ebenfalls auf der TOS-Diskette befindet und dort »MAKE_HLP.TTP« heißt.

Auf einer Partition (oder einer Diskette), auf der noch etwa 40 KByte frei sind, legen Sie sich einen Ordner an, den Sie z.B. »Help« nennen. In diesen Ordner kopieren Sie nun die Dateien »MAKE_HLP.TTP« und »HELP.TXT«. Das ist eine »Help«-Quelldatei, die Sie jetzt übersetzen. Starten Sie dazu »HELP_MAK.TTP« und tippen »HELP.TXT« in die Kommandozeile. Der Compiler wird dann eine Weile vor sich hin rodeln - falls Sie ihn auf einer Diskette arbeiten lassen, reicht die Zeit auf jeden Fall für einen Nescafé.

Bild 1. Das Zusammenspiel der Quellextdatei mit der Anzeige im Programm

Danach befinden sich in unserem Ordner vier neue Dateien: »HELP.ERR«, »HELP.AID«, »HELP.AIX« und »HELP.CNT«. In »HELP.ERR« sind etwaige Fehler protokolliert. Sie hat hier die Länge 0 Bytes, weil HELP.TXT eben keine Fehler enthält. Falls aber welche auftreten, sind die kritischen Stellen mit Angabe der Zeilennummer notiert, so daß Sie sie später leicht lokalisieren können. »HELP.AID« ist die Hilfetextdatei, »HELP.AIX« die entsprechende Indexdatei. Diese Dateien benötigt das Accessory. Sie sollten sie auf keinen Fall verändern - außer, Sie lieben Überraschungen.

Für Sie als Hilfe-Autor ist die letztgenannte Datei besonders interessant: »HELP.CNT« ist eine alphabetisch sortierte Liste von Verweisen auf alle existierenden Erklärungen. Damit ist das Anlegen eines Stichwortverzeichnisses ein Kinderspiel: Sie müssen nur »HELP.CNT« an geeigneter Stelle in Ihren Hilfe-Quell-text einfügen und ein bißchen bearbeiten - fertig. Eine kleine Einschränkung gibt es aber: Mehr als 300 Stichwörter verkraftet die Sortierfunktion nicht.

Das »Help«-Accessory

Nun benutzen wir den Hilfetext. Dazu installieren wir das Help-Accessory. Kopieren Sie die Dateien »HELP.ACC«, »HELP.AID« und »HELP.AIX« in das Hauptverzeichnis Ihrer Bootpartition oder Diskette. Nun noch ein Kalt- oder Warmstart, und schon können Sie »Help« ausprobieren. Sie müssen übrigens die Hilfe-Dateien nicht unbedingt in das gleiche Verzeichnis wie das Accessory legen. Wenn dieses beim ersten Aufruf die beiden Dateien nicht findet, fragt es Sie danach. Das Bedienen einer Datei-Aus-wahl-Box ist zwar kein Problem - nur lästig, wenn man es zu oft machen muß.

Sollte beim Benutzen des Accessories die Meldung »Zu wenig Speicher« auftauchen, dann geraten Sie nicht gleich in Panik: Damit ist der interne Speicher gemeint. »Help« begnügt sich nämlich mit einem Textpuffer von 15 KByte, was im Normalfall auch ausreicht. Sie können die RAMs also auf der Platine lassen.

Tips für Hilfe-Autoren

Zum Anlegen des Quelltextes sind Editoren besonders geeignet, welche die Benutzung von Accessories und den Aufruf externer Programme gestatten. So können Sie jederzeit den Compiler aufrufen und das Ergebnis sofort mit dem Accessory begutachten.

Die Zeilen des Quelltextes dürfen maximal 80 Zeichen lang sein, und im Hilfefenster können nie mehr als 80 Verweise gleichzeitig erscheinen. Aber die Erklärungen sollen ohnehin kompakt und übersichtlich sein. Gewöhnen Sie es sich also an, lieber mehrere kurze Erklärungen zu schreiben als wenige große. Die Länge des gesamten Quelltextes unterliegt keiner Beschränkung: Erlaubt ist alles, was noch auf auf den Massenspeicher paßt.

Der Hilfetext muß aber eine Erklärung zum Schlüsselwort »Übersicht« enthalten. Das Programm sucht diese Erklärung als erstes und nützt sie als Einstiegspunkt für alle anderen Erklärungen. Von hier aus verzweigt »Help« zu allen anderen Erklärungen.

Sie können auch Sonder- und Grafikzeichen in Ihren Hilfetexten verwenden. Einzige Ausnahme: der Backslash (umgekehrter Schrägstrich). Er ist normalerweise für Marken reserviert. Mit einem Trick bringen wir auch dieses Zeichen auf den Schirm: Schreiben Sie einfach »\«, dann erscheint an der betreffenden Stelle später ein einzelner Backslash. Schlüsselwörter dürfen dieses Zeichen nicht enthalten. Schlüssel dürfen übrigens nicht durch einen Zeilenumbruch unterbrochen werden und nicht länger als 30 Zeichen sein.

Wollen Sie Textstellen untereinander anzeigen lassen, beachten Sie, daß Marken im Hilfefenster nicht erscheinen. Deswegen verschiebt sich die Textausgabe hinter jedem Schlüssel gegenüber dem Quelltext um drei Spalten. Schauen Sie sich dazu den Hilfetext zum »Help«-Accessory auf unserer Diskette an.

Wenn Sie mit dem Schreiben beginnen, markieren Sie die Verweise besser noch nicht. Notieren Sie sich besser die Schlüsselwörter, zu denen Sie Erklärungen schreiben. Ist der Hilfetext fertig, nehmen Sie einen Editor, der Suchen und wahlweises Ersetzen enthält. Damit markieren Sie die Verweise halbwegs elegant. Gibt es z.B. eine Erklärung zum Begriff »Example«, dann ersetzen Sie überall dort, wo es sinnvoll erscheint, »Example« durch »<Example\« - fertig. Wenn in einer Zeile oder einem Absatz dreimal das gleiche Schlüsselwort vorkommt, reicht es aus, nur eines davon auch als Verweis zu kennzeichnen. Sonst müssen Sie sich nicht wundern, wenn Ihr Hilfetext in puncto Unübersichtlichkeit nur noch von Busfahrplänen und Schnittmusterbögen übertroffen wird.

Das war’s - noch nicht!

Jetzt können Sie mit »Help« Ihre Programme aufwerten. Die Programmierer kommen im zweiten Teil des Artikels auf ihre Kosten: Es gibt den Quellcode von »Help« (Turbo C) und eine Sammlung von C-Funktionen, mit denen Sie ohne großen Aufwand eigene GEM-Anwendungen mit integrierter Online-Hilfe entwickeln. Zu den Funktionen erhalten Sie eine Dokumentation im »Help«-Format. (ah)



Aus: TOS 02 / 1991, Seite 93

Links

Copyright-Bestimmungen: siehe Über diese Seite