WinHelp

Erstellung von Windows Hilfedokumenten mit einfachen Werkzeugen

Zur Erstellung kompletter Software-Dokumentation gehört neben gedruckten Werken auch eine Online Hilfe. Solche Hilfe-Dokumente haben den Vorteil, an jedem Computer-Arbeitsplatz verfügbar zu sein. Unter Windows lässt sich eine Hilfe-Datei (NAME.HLP) relativ leicht auch mit einfachen Werkzeugen erstellen. Benötigt werden ein (kostenloser) Microsoft Hilfecompiler (HCP für Windows 3.x und HCW für Windows 9x oder NT) sowie ein Editor zum Erstellen der Rohtexte im RTF-Format (Word). Texte lassen sich schnell layouten und mit Abbildungen sowie Hyperlinks gestalten. Der Aufbau der Compiler-Projektdatei (NAME.HPJ) wird erklärt.

Theorie

Die Hilferessourcen sollen dem Benutzer von Windows-Programmen eine Online Hilfe bieten. Dabei sollte grob zwischen reinen Hilfetexten und so genannten kontextsensitiven Hilfen unterschieden werden. Im ersten Fall entfällt der Datenbezug zum (Haupt-)Programm (Endung .exe oder .dll), im zweiten Fall werden Identifizierungs-Codes vom Programm an die Hilfedatei übergeben. Bei meiner Firma verwenden wir grundsätzlich die zweite (aufwändigere) Variante, daher muss ein enger Kontakt zwischen Programm-Entwickler und Hilfetext-Autor aufgebaut werden.

16-Bit Variante

Interessanterweise werden die Hilferessourcen unter DOS erstellt und compiliert, obwohl sowohl die Hilfetexte (im RTF-Format) als auch das Ergebnis (eine .hlp-Datei) ausschließlich unter Windows (3.x, 95, NT) zu gebrauchen sind. Aus der Geschichte dieses Hilfecompilers resultiert, dass er lediglich 16-Bit Applikationen liefert, was einerseits volle Kompatibilität zu allen Windows-Varianten gewährleistet, andererseits jedoch langsamer und unkomfortabler vonstatten geht. Das Endprodukt sieht für den Anwender auf den ersten Blick genauso aus, wie mit dem neuen Tool erstellt.

32-Bit Variante

Seit Windows 95 gibt es ein neues Tool zur Erstellung von Hilfe-Compilaten. Mit diesem Tool kann die gesamte Entwicklung unter Windows (9x oder NT) stattfinden. Allerdings ist das Ergebnis (die .hlp-Datei) als 32-Bit Version auch nur unter diesen Betriebssystemen lauffähig. Vorteile liegen besonders im Fehlen der Nachteile der 16-Bit Version, also schnelleres Compilieren, komfortableres Editieren und rein Windows-mäßiges Bearbeiten der Steuerdatei. Ferner ist die (vom Betriebssystem eingebaute) Suchroutine wesentlich umfangreicher und detaillierter geworden. Für Dokumente, die eine aufwändige Wortsuche benötigen, ist ausschließlich dieser neue 32-Bit Compiler zu empfehlen.

Werkzeuge/Tools

Ich verwende möglichst weit verbreitete Programme oder kostengünstige Shareware-Produkte.

  • Microsoft Word für Windows (bevorzugt Word 95, sehr ungern Word 97)
  • ASCII-Editor (Word oder Notepad tun es auch)
  • Hilfe-Compiler (entweder HCP oder das 32-Bit Tool HCW)
  • BMP-Bearbeitungsprogramm (z.B. Paint Shop Pro) optional für ScreenShots und deren Nachbearbeitung
  • SHG Segmented Hypertext Editor (SHED.EXE) optional für BMPs mit Links

Dateien und deren Formate

Zur Erstellung einer fertigen Hilfedatei werden verschiedene Daten- und Steuerdateien benötigt. Der Hilfecompiler generiert aus ihnen eine Datei mit der Kennung '.hlp'.

  • Tekom.hpj; Compiler Steuerdatei
  • Alias.txt; ASCII-Datei als Bindeglied zwischen SW-Entwickler und Hilfe-Autor (optional!)
  • Test.hid; ASCII-Datei vom SW-Entwickler mit Hilfe-Adressen (wichtig!)
  • Tekom.rtf; Word-Dokument im RichTextFormat mit den Hilfetexten des Autors
  • Abb_1.bmp; Abbildungen im Format BMP, SHG oder WMF
  • Tekom.hlp; Hilfedatei für Windows

Beispiele für diese Dateien wurden im Einzelnen erzeugt und gezeigt. Da der Aufbau der Steuerdatei etwas kryptisch erscheint, wurde ihm erhöhte Aufmerksamkeit geschenkt. Es sollten die Einträge in den Abschnitten der Projektdatei erklärt und gegebenenfalls Effekte durch Veränderungen dargestellt werden.
Ein anderer Schwerpunkt bezog sich auf das Word-Dokument (RTF). Gezeigt wurde, wie mit gängigen Absatzformaten und einfachen Word-Makros die Erstellung aufwändiger Hilfedateien möglich wird. Ganz bewusst wird auf den Einsatz von komplexen (aber auch komfortablen) Entwicklungswerkzeugen (wie DocToHelp, ForeHelp, RoboHelp, VB-Help) verzichtet, weil diese Werkzeuge teilweise die unbrauchbare Eigenschaft besitzen, die Sourcen so zu verändern, dass sie danach mit einfachen Mitteln (z.B. dem hier beschriebenen Word/HCW-Konstrukt) nicht mehr zu bearbeiten sind. Dadurch ist die Suche und Behebung von Fehlern erschwert und die fertige Hilfedatei oftmals unnötig groß, denn zusätzliche Datei-Organisations-Informationen müssen ebenfalls gespeichert werden. Durch die Verwendung von Makros und deren Nutzung über Schaltflächen erhält auch Word ein leicht verändertes Aussehen. Jedoch wurde gezeigt, dass nicht soviel Eingriff in Word notwendig ist wie bei anderen Hilfe-Entwicklungstools.
Zu betonen ist jedoch, dass meine Methode nur anwendbar ist, solange für Hilfeprojekte und Druckprojekte unterschiedliche Sourcen verwendet werden! Sobald man Single-Source-Publishing betreiben will, ist man auf komplexe Werkzeuge angewiesen, die - so zeigt deren Verbreitung - durchaus brauchbar sind.

Download Area

Die Liste wurde auf Grund der Anmerkung einer Interessentin aktualisiert. Insbesondere die Dokumentvorlage hlp_dot.zip wurde erweitert.

Makros in Word und/oder RTF

Auf Wunsch veröffentliche ich dort auch konkrete Beispiele. Ihr fragt mich per E-Mail, und ich versuche schnellstens zu einer Lösung beizutragen.

Links

Zu diesem Thema gibt es auch eine umfangreiche Website von Thomas Schulz.

Last modified: 24.09.2017