Erstellen von HTML Help Dateien

Geschrieben von: Hubert Daubmeier
Kategorie: Dokumentation

Dieser Artikel beschreibt kompakt worum es sich dabei handelt, wo die Vor- und Nachteile liegen und wie Sie es nutzen können. Und er zeigt wie Sie im Schnellgang eine eigene kompilierte Windows HTML Hilfedatei erstellen können.

Was sind HTML Help Dateien?

HTML Help (*.chm) ist das Nachfolgeformat der allseits bekannten HLP Hilfedateien. CHM Dateien sind komprimierte HTML Dateien, welche in einem Archiv gespeichert werden. Im CHM sind neben den HTML Dateien auch die abhängigen Objekte wie zB Grafiken gespeichert. Meist haben HTML Help Dateien einen Verzeichnisbaum der automatisch oder manuell erstellt und gepflegt werden kann. Weitere optionale Elemente sind ein Index (Schlüsselwortliste) und die notwendigen Daten zur Volltextsuche. Zahlreiche Beispiele finden Sie beispielweise im Verzeichnis c:\windows\help oder c:\winnt\help.

Warum HTML Help einsetzen?

HTML Help ist für Programmierer gedacht, die ihr eigenes Programm um ein Hilfesystem ergänzen oder eine Komponente dokumentieren wollen. Neben der klassischen Programmierung bieten sich CHM Dateien an, um einfach Offline Inhalte jenseits von Programmdokumentation bereitzustellen, um Zusammengehörendes, wie etwa eine Projektdokumentation, zusammenzupacken und als eine Datei ausliefern zu können. Die Komprimierung spart Platz und die eingebaute Navigation erleichtert den Einstieg.

Alternativen zu HTML Help sind PDF Dokumente, die neben dem Umstieg auf ein anderes Werkzeug nicht die Möglichkeiten von HTML bieten: zum Beispiel wird in CHM Dateien Scripting und Multimedia unterstützt. Ein Nachteil der HTML Hilfe ist die Plattformabhängigkeit.

Grundzüge der Erstellung von HTML Hilfe

Die Inhalte der Hilfe werden in HTML Seiten erstellt. Zum Erstellen der Seiten kann jeder HTML Editor eingesetzt werden. Eine (sehr) einfache Editor-Funktion ist im HTML Help Workshop selbst eingebaut.

Der oben erwähnte HTML Help Workshop ist das wichtigste Werkzeug bei der Erstellung von HTML Help Dateien. Es ist ein kostenlos ladbares Programm von Microsoft, das die folgenden Grundfunktionen und einiges darum herum beinhaltet:

• HTML Seiten hinzufügen und entfernen
• Inhaltsverzeichnis erstellen und verwalten
• Schlüsselwortliste erstellen und pflegen
• Optionen setzen, zB Volltextsuche ein- oder ausschalten
• Integriert den Hilfe Compiler, das Werkzeug, das alles zusammenmontiert, die Daten komprimiert und letztlich die endgültige Hilfedatei erstellt. Hinweis für alte Hilfeschreiber: es gibt keinen separaten HC.EXE mehr.

Zur Unterstützung des Autors gibt es mehrere kommerzielle Pakete wie z.B. RoboHelp oder HelpMagician, (mehr dazu auch unter HTML Help Sidebar) die komplexere Projekte ermöglichen. In diesem Artikel geht es um den Schnellstart ohne diese Hilfsmittel.

Zur Anzeige der HTML Help Datei werden Komponenten des Internet Explorers verwendet. Auf den Betriebssystemversionen nach Windows 95 sind üblicherweise alle Komponenten standardmäßig installiert. Die Internet-Einstellungen des Client-Rechners, wie Zeichensatz, Schriftgrößen oder Sicherheitseinstellungen werden vom Hilfesystem übernommen. Wer sich beispielsweise über zu große oder zu kleine Schrift wundert, weiß hiermit wo sich die Einstellung ändern lässt.

Legen wir los

Der HTML Help Workshop, den es übrigens nur in englischer Sprachversion gibt, kann von hier geladen werden (zum Zeitpunkt der Erstellung dieses Artikels war die HTML Help Version 1.32 aktuell). Beim Setup kann die Meldung "This Computer already has a newer version of HTML Help" erscheinen, die getrost ignoriert und übersprungen werden kann. Dahinter steht der Versuch die Windows Hilfe - das reine Anzeigewerkzeug, nicht das Autorenwerkzeug - in Form der HH.EXE zu aktualisieren; was sich etwa im Fall von Windows 2000 und höher erübrigt.

Nach der Installation findet sich im Startmenü eine Gruppe HTML Help Workshop, von der das gleichnamige Tool gestartet wird. Los geht es mit einer neuen Projektdatei über File - New - Project. Es wird ein Assistent mit den folgenden Schritten gestartet:

• Zuerst kommt der Vorschlag, ein altes Hilfeprojekt zu konvertieren. Wir gehen davon aus, daß kein altes HPJ Projekt der Vorgängerversion vorliegt und kreuzen das entsprechende Feld nicht an.
• Dann will der Wizard den Namen der Projektdatei wissen. Wechseln Sie per Browse- Schaltfläche in Ihr Arbeitsverzeichnis und geben als Namen "Demo" an. Die passende Erweiterung wird automatisch eingesetzt.
• Als weitere Annahme sind HTML Dateien bereits vorhanden und sollen eingebunden werden; die entsprechende Option aktivieren. Inhaltsverzeichnis und Index werden später erstellt, deshalb die zugehörenden Optionen leer lassen.
• Im letzten Dialog werden die HTML Seiten hinzugefügt. Der bekannte File Dialog unterstützt Mehrfachauswahl mit Umschalt- und/oder Steuerungstasten. Dateien aus verschiedenen Verzeichnissen werden durch Mehrfachklick auf Add hinzugefügt.

Nach Abschluß des Assistenten sollte es etwa so aussehen.

Ein Doppelklick auf einen beliebigen Eintrag im Options-Bereich oder das erste Icon in der vertikalen Symbolleiste am linken Rand öffnet den Eigenschaften Dialog des Projekts. Interessant hier: dem "Kind" unter Title einen Namen geben. Den Reiter wechseln zu Files und dort die Inhaltsverzeichnisdatei (contents file), automatische Erstellung es Inhaltsverzeichnis und die Überschriftentiefe (head level) auf vernünftigere 2 oder 3 stellen.

Damit könnte der erste Compilelauf stattfinden. Die Schaltfläche dazu findet sich auf der horizontalen Symbolleiste als drittes Symbol oder als Befehl im File Menü. Zum Betrachten der eben kompilierten Datei dient das vierte Symbol auf derselben Symbolleiste (neben dem Compilerknopf) oder als Befehl im View-Menü.

Projektdateien von Hand verwalten

Neugierig geworden? Nach den oben beschriebenen Schritten sieht die Projekt-Datei (Endung HHP für HTML Help Project) beispielsweise wie folgt aus:

[OPTIONS]
Auto TOC=2
Compatibility=1.1 or later
Compiled file=MeinProjekt.chm
Default topic=Demo.htm
Display compile progress=No
Language=0x407 Deutsch (Deutschland)
Title=Mein erstes Projekt


[FILES]
Demo3.htm
Demo2.htm
Demo1.htm

[INFOTYPES]

Interessant ist die Liste der eingebundenen HTML Seiten. Wer möchte, kann hier durchaus von Hand weitere Dateien einpflegen oder die Liste auf Vollständigkeit prüfen. Die Optionen werden praktischerweise besser im Workshop eingestellt. Selbstverständlich lassen sich auch die Dateien im HTML Help Workshop vollständig verwalten.

Inhaltsverzeichnis pflegen

Nach dem ersten Kompilierlauf findet sich das automatisch erzeugte Inhaltsverzeichnis als xxx.HHC Datei auf der Platte. Ab hier stellt sich die Frage, will ich die Datei weiterhin vom Workshop bei jedem Kompilierlauf neu erzeugen lassen oder stelle ich die automatische Generierung ab und pflege sie von Hand weiter. Es handelt sich um "handelsübliches HTML" ohne besondere Tricks, wie das folgende Beispiel verdeutlicht. Letztlich entscheidet persönliche Präferenz und die Erfordernisse des Projekts, sodaß es hier keinen allgemeingültigen Rat geben kann.

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<HTML>
<HEAD>
<meta name="GENERATOR" content="Microsoft&reg; HTML Help Workshop 4.1">
<!-- Sitemap 1.0 -->
</HEAD><BODY>
<UL>
  <LI> <OBJECT type="text/sitemap">
    <param name="Name" value="Einführung">
    <param name="Local" value="Demo1.htm">
    <param name="ImageNumber" value="1">
    </OBJECT>
  <LI> <OBJECT type="text/sitemap">
    <param name="Name" value="Funktionen">
    <param name="Local" value="Demo2.htm">
    <param name="ImageNumber" value="1">
    </OBJECT>
</UL>
</BODY></HTML>

Der Workshop ist hilfreich beim Arrangieren der einzelnen Überschriften. Reihenfolge und Gliederungstiefe lassen sich im Contents-Tab verschieben und anpassen. Per Doppelklick auf einen Inhaltseintrag öffnet sich die Eigenschaftenseite eines Eintrags. Im Tab Advanced können Sie den Image Index (gewissermaßen die Überschriftenebene) ändern. Wird dort die standardmäßige auto Einstellung abgewählt, lassen sich mit den Pfeilknöpfen alle Einträge beliebig verschieben.

Index erstellen

Ein Wort der Warnung: beim ersten Erkunden der Möglichkeiten bleibt es nicht aus, daß der Tab Index Interesse findet. Wenn Sie nicht jetzt gleich beabsichtigen die weitere erforderliche Arbeit in die Erstellung der Indexes zu investieren, brechen Sie beim Angebot einen automatischen Index zu erstellen besser ab, denn sonst ist Ihnen der erzeugte leere Index ständig im Weg und in der Ergebnisdatei stört ein leerer Index auch.

Was ist ein Index? Als sichtbares Ergebnis hat die fertige CHM Datei einen neuen Tab in der linken Navigationsleiste. Falls die Navigationsleiste nicht sichtbar ist, kann man diese per Klick auf den Einblenden-Button im Toolbar einschalten.

Der Index ist eine Liste von Begriffen, die nicht direkt mit dem Inhaltsverzeichnis zu tun haben müssen. Ein Doppelklick auf einen Indexeintrag zeigt die zugehörige Seite an (oder Seiten). Der Index macht es letztlich dem Leser leicht, auf unterschiedlichen Wegen zur gewünschten Information zu finden. Leider erfordert die Erstellung einiges an Arbeit; und mehr noch viel Nachdenken über gute Begriffe zur Aufnahme in den Index. Dem steht gegenüber, daß der Index von der Mehrheit der Benutzer als bevorzugte Suchmethode verwendet wird..

Der klassische Ansatz ist

• Im Projekt-Fenster den Tab Index aktivieren.
• Ein Klick auf das Schlüsselsymbol in der vertikalen Symbolleiste öffnet den Indexdialog.
• Unter Keyword eben dieses (ein Schlüsselwort) eintippen
• Über die Add-Schaltfläche wird die zugehörige Datei angegeben. Enthalten mehrere Dateien einen Bezug zu diesem Schlüsselwort, werden alle zutreffenden Dateien angegeben.

Als andere Variante können die Keywords direkt im HTML Code eingebettet werden, wie das folgende Beispiel zeigt.

<Object type="application/x-oleobject" classid="clsid:1e2a7bd0-dab9-11d0-b93a-00c04fc99f9e">
  <param name="Keyword" value="Accept">
  <param name="Keyword" value="ConnectionTimeout">
  <param name="Keyword" value="TrustUnknownCA">
  <param name="Keyword" value="UserAgent">
</OBJECT>

Eine dritte Variante, die sich bei größeren Projekten empfiehlt, ist die Pflege des Index außerhalb des HTML Help Workshops. Denn in der Praxis passiert folgendes: in verschiedenen Seiten taucht der gleiche Begriff mehrmals unter unterschiedlichen Keywords auf. Beispiel: "Anlage", "Anlagen" und "Attachment". So etwas sehe ich teilweise in der fertigen Hilfedatei. Die Pflege wird jedoch umständlich. Hinzu kommt, daß bei der Durchsicht der Schlüsselwörter einfacher auffällt, daß der Benutzer möglicherweise gar nicht an "Anlagen" denkt und folglich der Sucherfolg ganz einfach gesteigert werden kann mit zusätzlichen Schlüsselwörter wie etwa "Datei anfügen" und "Anhängen".

Praktischer ist es, in diesem Fall den Index in einer Excel-Datei zu pflegen. Beim Erstellen des Indexes hilft ein kleines Script.

Als Vorbereitung braucht es eine Exceltabelle mit zwei Spalten. In der ersten steht der Dateiname der HTML-Seite und in der zweiten Spalte wird das Schlüsselwort eingetragen. Je Seite können mehrere Schlüsselworte eingetragen werden. Es wird einfach der Dateiname wiederholt und das neue Schlüsselwort eingetragen. Auf diese Art kann man einfach nach Schlüsselworten sortieren und sich die Pflege deutlich erleichtern. Das Beispiel im Download verdeutlicht das Prinzip noch einmal.

  Option Explicit
  Const CDATABASE = "keywords.xls"
  Const OUTPUTDATEI = "meinprojekt.hhk"
  Const OVERWRITE = True
  Dim oRS, oConn, fso, KeyDatei, strOutput
  strOutPut = vbTab & "<LI> <OBJECT type=""text/sitemap"">" & vbCrLf & _
    vbTab & vbTab & "<param name=""Name"" value=""yyyy"">" & vbCrLf & _
    vbTab & vbTab & "<param name=""Local"" value=""xxxx"">" & vbCrLf & _
    vbTab & vbTab & "</OBJECT>" & vbCrLf

  Set fso = CreateObject("Scripting.FileSystemObject")
  Set KeyDatei = fso.CreateTextFile(OUTPUTDATEI, OVERWRITE)
  WriteHead()
  Readdb
  WriteFooter()
  KeyDatei.Close
  MsgBox "Fertig"


  Sub Readdb()
    Set oConn = CreateObject("ADODB.Connection")
    oConn.Open "Provider=Microsoft.Jet.OLEDB.4.0;Excel 8.0;DATABASE=" & CDATABASE
    Set oRs = oConn.Execute("SELECT * FROM Datenbank ORDER BY 2")
    Do Until oRs.eof
      KeyDatei.write Replace(Replace(strOutPut, "xxxx", oRS(0)), "yyyy", oRS(1))
      oRs.MoveNext 
    Loop 
    oRs.close
    oConn.close 
  End Sub


  Sub WriteHead()
    KeyDatei.Write "<HTML>" & vbCrLf & "<HEAD>" & vbCrLf & _
      "<!-- Sitemap 1.0 -->" & vbCrLf & "</HEAD>" & vbcrlf & _
      "<BODY>" & vbCrLf & "<UL>" & vbCrLf
  End Sub


  Sub WriteFooter()
  	KeyDatei.Write "</UL>" & vbCrLf & "</BODY></HTML>"  	
  End Sub

Volltextsuche

Nach der Arbeit mit dem Index ist die Volltextsuche ziemlich einfach zu implementieren. Das Eigenschaftenfenster des Projekts öffnen und im Tab Compiler die Checkbox "Compile fulltext search information" einschalten. Aber Vorsicht, die Dateigröße wird deutlich größer. Ist Platz bzw. Übertragungsgeschwindigkeit ein Thema, wäre zu überlegen, ob es das Feature wert ist. Es kommt hinzu, daß in der Praxis so mancher Benutzer eine Volltextsuche nicht verwendet.

Für Leute, die sich trauen die Volltextsuche zu verwenden ist es jedoch einfach und praktisch. Als Beispiel könnte man auf die Idee kommen, die Dateien von SelfHTML in eine CHM Datei zu packen um sie hinterher per Volltextsuche zu durchsuchen. Als kleinen Bonus finden Sie ein Script im Download, das bei der Erstellung der Dateienliste hilft. Für eine vollautomatische Generierung einer SelfHTML in CHM-Format mit Volltextsuche reicht es allerdings noch nicht ganz aus. Wenn Sie aber die automatische Erzeugung des Inhaltsverzeichnisses abschalten steht zumindest einem ersten Schnelltest nichts mehr im Weg.

Einige Tips

• Zum Lernen ist es hilfreich eine vorhandene CHM Datei auseinander zu nehmen (Decompile im File Menü) und sich die Arbeit anderer Hilfeautoren anzusehen.
• Der Help Compiler ist arg beleidigt, wenn zum Kompilieren die aktuelle Hilfedatei noch geöffnet ist, denn dann kann er die alte Datei nicht löschen um eine neue anzulegen. Also vor dem Kompilieren zuerst die zuletzt erstellte Datei schließen.
• Der HTML Help Image Editor in der gleichen Programmgruppe wie der HTML Help Workshop ist ein kleines Tool zum Erstellen von Bildschirmkopien; es kann Bilder zuschneiden und Farben verändern. Praktisch ist es für die Erstellung von Imagemaps. Und eine neckische, aber recht brauchbare Funktion findet sich im Datei-Menü unter dem Befehl "Art Manuscript". Dies läßt sich mal schnell dazu "mißbrauchen", eine webfähige Übersicht der Bilder einer Digitalkamera zu erstellen. Gestartet wird der Assistent über den Befehl: Datei - Art Manuscript - Create or Update. Ein Assistent bietet Erklärungen und führt durch die einzelnen Schritte. Am Ende werden aus allen angegebenen Grafiken Miniaturbilder mit Diarahmen generiert, die dazu passenden HTML Datei erstellt und die Miniaturbilder mit den großen Originalbildern verlinkt. Sind es gar zu viele Grafiken, erstellt der Assistent auch mehrere Übersichtsseiten und verlinkt sie untereinander.
• Wie schon erwähnt werden zur Anzeige der Hilfedateien die Komponenten des Internet Explorers verwendet. Das bedeutet, daß man auch dessen Befehle verwenden kann: zB Rechtsklick und Quelle anzeigen, oder Bilder kopieren. Als weitere praktische Konsequenz daraus läßt sich problemlos VBScript als Clientsprache einsetzen.

Schlußbemerkung

Mein besonderer Dank gilt Dominik-Pascal Kovacic-Voß, Frank Matthiesen und Jens Lukas für Ihre Durchsicht und die kritischen Beiträge bei der Erstellung dieses Artikels. Ich hoffe, wir konnten Ihnen eine praktische und nachvollziehbare Anleitung zum Erstellen von CHM Dateien liefern. Es stecken noch viele Möglichkeiten im System, die heute in der Kürze eines Artikels nicht angesprochen werden konnten.

Download des Codes

Klicken Sie hier, um den Download zu starten.

Verwandte Artikel

C# XML-Kommentare — Dokumentation von selbst
Schreib"kunst" für Programmierer, Teil I

Links zu anderen Sites

HTML Help Download
HTML Help Sidebar

Wenn Sie jetzt Fragen haben...

Wenn Sie Fragen rund um die in diesem Artikel vorgestellte Technologie haben, dann wenden Sie sich bitte an die AspGerman Listen. Die Teilnehmer dieser Liste(n) helfen Ihnen gerne, wenn Sie sich zur im Artikel vorgestellten Technologie weiterbilden möchten.

Haben Sie Fragen die sich direkt auf den Inhalt des Artikels beziehen, dann schreiben Sie dem Autor! Unsere Autoren freuen sich über Feedback zu ihren Artikeln. Ein einfacher Klick auf die Autor kontaktieren Schaltfläche (weiter unten) und schon haben Sie ein für diesen Artikel personalisiertes Anfrageformular.

Und zu guter Letzt möchten wir Sie bitten, den Artikel zu bewerten. Damit helfen Sie uns, die Qualität der Artikel zu verbessern - und anderen Lesern bei der Auswahl der Artikel, die sie lesen sollten.