CHM-Hilfe

Hierbei geht es um Tipps und Tricks bei der Erstellung von CHM-Dateien, so 'ne Art geziptes HTML, funktioniert ab Windows 98 bis heute. Unter Linux sind einige geeignete Betrachter verfügbar. Leider (oder zum Glück?) ist die Browser-Fähigkeit begrenzt, in etwa auf Internet Explorer 7.

CHM wird ab Windows 98 durchgängig unterstützt, ist also quasi gemeinsam mit USB verfügbar. Die alte RTF-basierte Hilfe ist ab Vista nicht mehr da und muss extra installiert werden.

Ein Beispiel⚓

*.hhp (Projektdatei): ZeilennummernUmbruch

[OPTIONS]
Binary TOC=Yes
Compiled file=gwbasic.chm
Default Window=main
Contents file=gwbasic.hhc
Index file=gwbasic.hhk
Default topic=default.html
Full-text search=Yes
Language=0x409 Englisch (USA)
Title=GW-BASIC User's Guide

[WINDOWS]
main=,"gwbasic.hhc","gwbasic.hhk","default.html","default.html",,,,,0x62520,,0x70384E,,,,,,,,0
popup=,,,,,,,,,0,,0x80,,,,,,,,

[FILES]
gwbasic.hhp
chapter1.html
…

Die Angaben bei main generieren alle erdenklichen (sinnvollen!) Extra-Knöpfe, nämlich Browse-Buttons, History zurück und vorwärts, Rückwärtssuche sowie Einstellen der Schriftgröße.

Das 0x80 bei popup generiert ein ToolWindow mit schmaler Titelzeile.

Wichtig zu wissen:

Dateinamen dürfen kein Leerzeichen enthalten, sonst klappt die Browse-Funktion nicht!
*.hhc und *.hhk müssen tatsächlich doppelt in der *.hhp-Datei vorhanden sein, sonst klappt die Rückwärts-Suche (= Finden des Abschnitts im Inhaltsverzeichnis) nicht.
Das Wechseln des Fenstertitels anhand des HTML-Titels funktioniert schlichtweg nicht.
Die einzelnen HTML-Titel werden für die Auflösung mehrfacher Index-Einträge benötigt, aber nur wenn sie nicht im Inhaltsverzeichnis (*.hhc) stehen.
Ohne Angaben von Fenstergrößen merkt sich Windows die zuletzt benutzte Größe und Position, daher am besten nichts angeben
Die [FILES]-Sektion kann leer bleiben. Nützlich für die Dekompilierung ist jedoch die Projektdatei, die als einzige nicht mit aufgenommen wird. Unbedingt müssen hier Dateien gelistet werden, die per <iframe src=… aufgenommen werden.

Ungelöst:

Kleine Knöpfe (wie SelfHTML.chm)

*.hhc (Inhaltsverzeichnis):

<HTML><HEAD><!-- Sitemap 1.0 --></HEAD><BODY><UL>
 <LI><OBJECT type="text/sitemap"><param name="Name" value="Chapters"><param name="Local" value="default.html"></OBJECT>
 <UL>
  <li><object type="text/sitemap"><param name="Name" value="1. Welcome"><param name="Local" value="Chapter1.html"></object>
  …
 </UL>
 <LI><OBJECT type="text/sitemap"><param name="Name" value="Appendicies"></OBJECT>
 <UL>
  <li><object type="text/sitemap"><param name="Name" value="A. Error Codes and Messages"><param name="Local" value="AppendixA.html"></object>
 </UL>
 <li><object type="text/sitemap"><param name="Name" value="Glossary"><param name="Local" value="Glossary.html#1"><param name="New" value="1"></object>
</UL></BODY></HTML>

Nicht jeder Knoten muss eine dahinter stehende URL haben. Leider gibt's da keinen Automatismus, mit dem Windows bspw. ein anderes Icon benutzt.

Alles in allem ziemlich geschwätzig; ein Texteditor mit regulären Ausdrücken und Wortersetzung ist hier zweckmäßig. Es kommt der Eindruck auf, das Microsoft die Programmierer quälen möchte. Eine simple ASCII-Datei mit verschiedenen Einrücktiefen und gewöhnlichen HTML-Links hätte es ja auch getan.

Hochkommas kann man weglassen, wo kein Leerzeichen eingeschlossen ist.

Wichtig zu wissen:

Das mit den Tree-Icons funktioniert nur bei ausgeschaltetem „Binary TOC“! Immerhin generiert Windows von selbst einigermaßen „passende“ Icons. Nur das "New"-Tag (<param name="New" value="1">) funktioniert zuverlässig. Es generiert einen auffälligen „Lichtpunkt“ auf dem Icon.
Ordner-Symbole statt Bücher erzeugen die Zeile:
```
 <OBJECT type="text/site properties"><param name="ImageType" value="Folder"></OBJECT>
```
direkt nach <BODY>, aber eben nur bei ausgeschaltetem „Binary TOC“! Andere Features sind ImageList mit Image Width.
Alles was im Inhaltsverzeichnis ist, ist auch in der Browse-Reihenfolge. Leider auch die lokalen Labels (also <a name=…>). Daher sollten diese eher sparsam (im Inhaltsverzeichnis) verwendet werden. Alles, was nicht drinsteht, ist auch nicht in der Browse-Sequenz! Die Browse-Buttons schalten automatisch auf grau am Anfang und Ende der Sequenz bzw. wenn ein Thema nicht im Inhalt steht.
Alle <OBJECT …>-Geschichten werden effektiv entfernt und ersetzt! Diese steuern also allesamt den Browser (oder den Hilfe-Compiler?). Verballhorntes XML schon wieder.
Der -Kommentar muss stehen bleiben! Alles andere (!DOCTYPE… und meta generator…) kann weg. Unnötiges Geschwafel bläht ja nur das fertige .CHM auf.
Mehrfache Nennungen eines Dokuments sind im Inhaltsverzeichnis zu vermeiden. Wenn doch, muss die Bezeichnung (Titel) immer dieselbe sein! Sonst dupliziert der .CHM-Betrachter einfach die zuletzt genannte Bezeichnung! Notfalls behilft man sich mit verschiedenen #-Ankern.
UTF-8 und Umlaute? Fehlanzeige! Die Datei muss mit ANSI-Kodierung erstellt werden und darf nichts anderes als den ANSI-Zeichensatz verwenden (m.a.W. Ω für Ω geht nicht)

*.hhk (Index = Schlüsselwörter):

<HTML><HEAD><!-- Sitemap 1.0 --></HEAD><BODY><UL>
 <li><object type="text/sitemap"><param name="Name" value="ABS"><param name="Local" value="ABS.html"></object>
 <li><object type="text/sitemap"><param name="Name" value="ASC"><param name="Local" value="ASC.html"></object>
 … 
</UL></BODY></HTML>

Auch hier wieder viel Blabla. Reguläre Ausdrücke helfen, eine Wortliste entsprechend umzuformen.

Wichtig zu wissen:

Die Stichworte MÜSSEN (praktisch) in alphabetischer Reihenfolge stehen, so wie es der Anwender erwartet.
Schachtelungen sind erlaubt
Gleiche Stichwörter mit verschiedenen HTML-Zielen sind erlaubt und führen zu einem Auswahldialog, der für jeden Treffer:
- den „Titel“ der HTML-Datei, das ist der Titel im Inhaltsverzeichnis(!), sofern dort vorhanden, sonst der HTML-<title>-Tag
- den „Titel“ der CHM-Datei (also den Fenstertitel, siehe HHP-Datei, [Options] Title=)
anzeigt.
Gleiche Stichwörter mit gleichen HTML-Zielen werden unterdrückt.
UTF-8 und Umlaute? Fehlanzeige! Wie oben bei *.hhc.

Ungelöst:

Wie man ein Popup in passender Größe ohne Rollbalken erzeugt

Tipps (HTML)⚓

Da die HTML-Dateien ziemlich lausig gepackt werden sollten unnötige Bestandteile möglichst vermieden werden, um das resultierende .CHM klein zu halten:

Kein <META HTTP-EQUIV="Content-Type" content="text/html; charset=utf-8">. Um sicher zu gehen, dass UTF-8 benutzt wird, genügt eine BOM.
1 globales Stylesheet verwenden: <link rel=stylesheet href="cs.css">
1 globales JavaScript verwenden: <script src="js.js"></script> falls erforderlich
Kein <title>Titel</title>. Er wird bei .CHM schlichtweg nicht verwendet, außer die Seite ist nicht im Inhaltsverzeichnis (*.hhc). Dann und nur dann wird dieser im Index (*.hhk) oder bei der Ergebnisliste der Volltextsuche angezeigt.
Unsauber, aber man kann sogar auf den gesamten Header verzichten und alles in eine mehr oder weniger nackte Textdatei stecken
Unix-Zeilenenden ("\n")

HTML zersägen⚓

Macht sich gut, wenn man fürs Web die gleiche HTML-Datei in einem Stück haben möchte!

<object type="application/x-oleobject" classid="clsid:1e2a7bd0-dab9-11d0-b93a-00c04fc99f9e">
 <param name="New HTML file" value="USB-Funktionen.htm">
 <param name="New HTML title" value="USB-Funktionen">
</object>

Die Angabe „HTML-Titel“ kann man sich sparen, wenn die HTML-Seite im Inhaltsverzeichnis erscheint; jener Titel wird immer dann verwendet, etwa bei der Auflösung von Mehrfachreferenzen im Index.

Unbedingt einen <body>-Tag ganz am Anfang einbauen! Sonst stürzt der Hilfe-Compiler ab. Weiteres HTML-Gesülz wird nicht benötigt.

Zersägte Dateien klein halten:

Datei als UTF-8 mit BOM abspeichern
Umlaute und Sonderzeichen ganz normal verwenden
Im Header nur <style … (und <body>) unterbringen

Möchte man das seitenweise HTML-Ausdrucken unterstützen, passt da auch ein

<br clear=all style='page-break-before:always'>

davor.

Die Links im Inhaltsverzeichnis und Index müssen sich auf die zersägten Dateinamen beziehen!

Womöglich kann man sogar Inhaltsverzeichnis und Index mit hineinstecken.

HTML5-Anzeige⚓

Egal wie neu der installierte Internet Explorer ist, bei .CHM-Dateien kennt der Browser einfach keine HTML5-Features, etwa das <canvas>-Tag.

Hierzu muss man in der Registrierung einen Eintrag vornehmen. Für den Aufruf aus einer selbst geschriebenen Echse heraus muss dessen Name anstatt hh.exe stehen.

Windows Registry Editor Version 5.00

[HKEY_USERS\S-1-5-21-1559349094-3728892266-3505865260-1007\Software\Microsoft\Internet Explorer\Main\FeatureControl\FEATURE_BROWSER_EMULATION]
"hh.exe"=dword:00002710

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Internet Explorer\MAIN\FeatureControl\FEATURE_BROWSER_EMULATION]
"hh.exe"=dword:00002710

Dieses Manko hat MS Help 2 (*.HxS) zwar nicht, aber hier sind die übrigen Probleme noch größer.

Tricks⚓

HHP-Datei selbst erstellen⚓

Von einem vorhergehenden Projekt kann man einfach die HHP-Datei kopieren und die Strings entsprechend anpassen.

Die [Files]-Sektion kann leer bleiben, da alle abhängigen Dateien automatisch hineingepackt werden. Nur die HHP-Datei wird als einzige nicht hineingesteckt (siehe nächster Tipp), da diese in compilierter Form in der „#SYSTEM“-Datei vorliegt.

Quelle sparen⚓

Da die Total-Commander-Packer-Erweiterung ChmDir den bequemen Zugriff auf den Inhalt einer .CHM-Datei erlaubt, ist es zweckmäßig, bei [Files] auch die *.hhp-Datei hineinzustecken. So hat man jederzeit die komplette Quelle verfügbar, ohne dafür ein extra Verzeichnis herumschleppen zu müssen.

Das beißt sich allerdings mit der Möglichkeit, HTML-Dateien zu zersägen.

Die gleiche Funktionalität bietet 7zip im Windows-Explorer. Leider sind die Datumsangaben der Dateien futsch. Die üblichen Auspack-Programme setzen diese auf das Datum der CHM-Datei.

Unverständlich erscheint es, dass der Hilfe-Compiler die Inhalts- und Indexdateien (HHC und HHK) mit hineinsteckt, obwohl diese, bei aktiviertem Binary TOC, bereits in versteckten Binärdateien hineincompiliert sind. Man muss diese ggf. nachträglich mit dem Total-Commander-Tool herauslöschen.

Clientseitige Syntaxhervorhebung⚓

Ist nunmehr als Teil meiner universellen h.js realisiert. Zeilen 308 … 466, also gar nicht übermäßig viel.

Funktionierendes Beispiel.

CHM-Darstellung auf Webseiten⚓

Manch einem trifft gewisses Unbehagen, CHM-Dateien zu erstellen, weil man für's Web alles noch einmal machen müsste. Kann man nicht CHM-Dateien im beliebigen Web-Browser darstellen?

Dies ist mittels viewchm.php und dem auf chmlib aufsetzenden unchm.c bei mir gelöst. Noch unfertig, keine Volltextsuche, und die Browse-Buttons funktionieren nicht. Hier ein (anderes) Beispiel. Die PHP-Datei benötigt derzeit Shell-Aufrufe und ist für hochsichere Server und kostenlose Webspaceanbieter nicht geeignet.

Da die typische CHM-Darstellung einer Frame-Aufteilung am besten nahekommt, ist es hier auch so implementiert. Das ist zweifelsohne Smartphone-inkompatibel. Eine gesonderte Smartphone-Unterstützung — erfordert eine völlig andere Präsentations-Struktur womöglich mit einem iframe für Inhalts- und Stichwortverzeichnis.

HTML-Seite im CHM?⚓

Manchmal will oder muss man HTML-Seiten erstellen, die sich in CHM-Umgebung anders verhalten sollen als bspw. mit dem vorangegangenen viewchm.php. Ganz einfach: Die URL einer CHM-Datei enthält stets zwei Doppelpunkte hintereinander, was auf einem Webserver sicherlich nie vorkommt.

 var inside_chm = location.href.indexOf("::") >= 0;

Persistente Einstellungen⚓

Für das Erstellen einer Dokumentation ist es sehr nützlich, irrelevante Informationen automatisch ausblenden zu lassen. Beispiele:

Bevorzugte Programmiersprache: Bei Auswahl von C sollen Beispiele in C# unterdrückt werden
Verwendeter Mikrocontroller: Bei Auswahl eines ATtiny13 sollen die Features eines ATmega8 gar nicht angezeigt werden.
Elektronisches Sprachlehrbuch: Speicherung der aktuellen Lektion / Wortschatzes sowie Ablage von Ergebnissen aus Übungsaufgaben
Elektronisches Testat: Online-Prüfung und Ablage der Ergebnisse in externer Datei oder externem Cookie (Sicherheitsproblem bzgl. Betrugsprävention)

Die Vorgehensweise ist, in die betreffenden Seiten ein <iframe> mit einer immer gleichen Webseite einzubauen. Da Cookies nicht funktionieren, speichert dieses iframe seinen Zustand in parent.name! Dadurch ist der Zustand leider nicht persistent zwischen dem Schließen und erneutem Öffnen der CHM-Datei. Nur damit viewchm.php nicht mit dem wechselnden Namen des rechten Frame-Fensters durcheinanderkommt, besser mit Fallunterscheitung:

// Lesen:
 val = inside_chm ? parent.name : document.cookie;
// Schreiben:
 if (inside_chm) parent.name = val; else document.cookie = val;

Und hier ein praktisches Beispiel.

Echte Peristenz in CHM-Dateien⚓

Das geht nicht ohne Verrenkungen. Entweder eine (nur eine) externe HTML-Datei, damit Cookies funktionieren. Die passende URL beschaffen. Oder irgendwas mit ActiveX und Dateizugriff (muss ich noch mal finden).

Persistente Einstellungen für jede Seite⚓

Es ist natürlich mühselig, für jede einzelne Webseite das iframe einzubinden. Da jede Seite ohnehin einen Bezug zur global.css und global.js braucht, kann das Javascript dieses iframe dynamisch generieren.

Weiterhin ist es nützlich, für verschiedene Browser und verschiedene Größen von Eingabeelementen das iframe genau passend zu machen. Da dies window.getComputedStyle erfordert, geht das nur mit neueren Browsern, also bspw. mit viewchm.php und aktuellem Browser.

 if (window.getComputedStyle) {
   var cs = window.getComputedStyle(sel);		// sel = Eine Combobox; Firefox liefert Höhe = "21px"
   var fr = parent.document.getElementsByTagName("iframe")[0];
   fr.style.width = cs.width;
   fr.style.height = cs.height;	// Größe anpassen
   fr.style.right = 0;
   fr.style.top = 0;		// in die obere rechte Ecke platzieren (das <iframe> hat CSS position:fixed)
 }