Apple-Handbücher (Apple Help Books) sind eigentlich nur eine Ansammlung von gewöhnlichen HTML-Dateien in einem Ordner. Dazu ein paar Bilder, vielleicht CSS-Dateien und ein Helpindex, fertig ist das Apple-Hilfe-Buch. – Soweit die Werbung.
Wir machen das natürlich mit UDO, dem Universellen DOkument-Format-Programm. UDO kann auf Knopfdruck fertige HTML-Dateien für das Apple-Hilfe-Buch-Format erzeugen. Wenn Sie sich dafür interessieren, wie einfach Sie Handbücher in verschiedensten Formaten aus einem simplen Quellformat erzeugen können, schauen Sie sich UDO einfach mal an. Ansonsten können Sie natürlich zum Erzeugen Ihrer HTML-Dateien verwenden, was Sie wollen.
Wichtig ist eigentlich nur, dass die index.htm (oder wie immer Ihre Einstiegsseite ins Hilfe-Buch heißt) folgende Zeilen im HTML-Kopf hat:
<meta name="AppleTitle" content="iCalamus Help">
<meta name="AppleIcon" content="iCalamus%20Help/img/iC_feather_16.png">
Diese Beispielzeilen beziehen sich auf unsere iCalamus-Hilfe-Bücher. Natürlich werden die content-Inhalte bei Ihnen anders heißen. Beachten Sie, dass Leerzeichen (und ggf. lokalisierte Sonderzeichen) korrekt im URL-Format codiert werden müssen!
Die Hilfe-Bücher müssen im Ordner Resources und dort jeweils in den lokalisierten .lproj-Ordnern liegen. Diese Hilfe-Ordner können alles Mögliche enthalten, z.B. weitere Unterordner für Bilder oder CSS-Dateien. Es empfiehlt sich, eine index.htm o.ä. als Startseite direkt im Hilfe-Ordner zu platzieren, auch wenn weitere Hilfebuch-Seiten ggf. in Unterordnern stecken.
Wichtig: Leider kann der Apple Help Viewer bisher nur innerhalb eines Hilfe-Ordners referenzieren. Daher ist es leider nicht möglich, z.B. von allen Sprachen gemeinsam genutzte Bilder in einem gemeinsam genutzten Ordner außerhalb der verschiedenen lokalisierten Hilfe-Ordner zu platzieren. Das kann das Programmpaket ggf. etwas aufblähen.
Wir schlagen vor, dass Sie trotz der Lokalisierbarkeit der Apple-Handbücher einen einheitlichen Ordnernamen für die Hilfe-Bücher wählen. Innerhalb der Resources-Ordner des Programmpakets spielt die Lokalisierung von Ordnernamen eine untergeordnete Rolle.
Tragen Sie in der Info.plist Ihres Programmes zwei neue Key-Value-Paare wie folgt ein:
<key>CFBundleHelpBookFolder</key>
<string>iCalamus Help</string>
<key>CFBundleHelpBookName</key>
<string>iCalamus Help</string>
Damit weiß der Apple Help Viewer erstmal generell Bescheid über ein nicht lokalisiertes Hilfe-Buch Ihres Programms.
Wir gehen davon aus, dass Sie in Ihrem Resources-Ordner die sprachspezifischen Dateien (.nib, .strings usw.) schon in Sprachen-Ordnern organisiert haben. Früher wurden meist Ordnernamen wie English.lproj, German.lproj usw. genutzt. Apple empfiehlt jetzt, die ISO-Bezeichnungen zu nehmen, so dass die eben genannten Beispiel-Ordner nun besser en.lproj und de.lproj heißen.
Legen Sie folgende Dateien an, falls sie nicht schon existieren (wir nehmen hier einfach mal die bisher existierenden Sprachen von iCalamus als Beispiel):
/Resources/English.lproj/InfoPlist.strings
/Resources/cs.lproj/InfoPlist.strings
/Resources/da.lproj/InfoPlist.strings
/Resources/de.lproj/InfoPlist.strings
/Resources/fr.lproj/InfoPlist.strings
/Resources/it.lproj/InfoPlist.strings
/Resources/lv.lproj/InfoPlist.strings
/Resources/nl.lproj/InfoPlist.strings
/Resources/pl.lproj/InfoPlist.strings
/Resources/sv.lproj/InfoPlist.strings
Nun tragen Sie in jeder dieser Dateien den jeweils lokalisierten String für CFBundleHelpBookName ein, also z.B. so (natürlich nehmen wir einfach wieder unser iCalamus-Beispiel):
English.lproj/InfoPlist.strings:
CFBundleHelpBookName = "iCalamus Help";
cs.lproj/InfoPlist.strings:
CFBundleHelpBookName = "Nápověda iCalamusu";
da.lproj/InfoPlist.strings:
CFBundleHelpBookName = "iCalamus-hjælp";
de.lproj/InfoPlist.strings:
CFBundleHelpBookName = "iCalamus-Hilfe";
fr.lproj/InfoPlist.strings:
CFBundleHelpBookName = "Aide d'iCalamus";
it.lproj/InfoPlist.strings:
CFBundleHelpBookName = "Aiuto iCalamus";
lv.lproj/InfoPlist.strings:
CFBundleHelpBookName = "iCalamus palīdzība";
nl.lproj/InfoPlist.strings:
CFBundleHelpBookName = "iCalamus Help";
pl.lproj/InfoPlist.strings:
CFBundleHelpBookName = "Pomoc iCalamusa";
sv.lproj/InfoPlist.strings:
CFBundleHelpBookName = "iCalamus Hjälp";
Dadurch weiß der Apple Help Viewer, mit welchen lokalisierten Namen er die lokalisierten Hilfe-Bücher in seinem Library-Menü auflisten soll.
Sie müssen Cocoa sagen, dass es nach dem Aufruf eines bestimmten Menüeintrags den Apple Help Viewer aufrufen soll. Öffnen Sie dazu in allen Sprachversionen Ihr Programmmenü MainMenu.nib im Interface Builder und verknüpfen Sie den Menüeintrag 'Hilfe > Programmname-Hilfe' mit der Aktion [NSApplication showHelp]. (Selektieren Sie in IB den entsprechenden Menüeintrag, öffnen Sie dann den Inspektor und wählen Sie 'Connections > Target/Action': showHelp:.
Diese Funktion gehört zur Klasse NSApplication und braucht von Ihnen im Sourcecode Ihres Programms nicht weiter aufgerufen zu werden. Im NIB ist schon alles entsprechend verdrahtet. Also: Null Zeilen Code zum Aufrufen Ihrer Hilfe-Bücher!
Damit der Apple Help Viewer schneller in Ihren Hilfe-Dateien bestimmte Stichwörter findet, müssen diese zunächst indiziert werden. Dazu brauchen Sie den Help Indexer. Dieses Tool finden Sie normalerweise hier:
/Developer/Applications/Utilities/Help Indexer.app.
Wenn Sie den Help Indexer starten, sehen Sie erstmal nur einen simplen Dialog:
Klicken Sie hier auf 'Select' und suchen Sie den Hilfe-Ordner der ersten Sprache, zu der Sie einen Hilfe-Index generieren wollen (in unserem nachfolgenden Beispiel Tschechisch).
Anschließend sollte der Help Indexer etwa so aussehen:
Klicken Sie jetzt noch nicht auf 'Create Index'! Erst sollten Sie noch ein paar Einstellungen vornehmen. Rufen Sie dazu den 'Preferences'-Dialog des Help Indexers auf – Sie wissen schon, wo.
Spannend sind hier die Optionen 'Use remote root for missing files and updates' sowie 'Prefer network files to local files'. Hiermit können Sie die eigentliche Eleganz des Apple Help Viewers einschalten, nämlich dass er grundsätzlich erstmal versuchen soll, die angeforderten Hilfe-Seiten online von Ihrem Server zu holen, statt die (evtl. schon wieder veralteten Seiten) aus Ihrem Programmpaket zu laden. Stellen Sie im Eingabefeld Ihren Handbuchpfad ein, entsprechend unserem Beispiel.
Jetzt können Sie den Einstellungen-Dialog mit 'OK' schließen und den ersten Index generieren. Sie sehen anschließend im Hilfe-Ordner eine Datei namens iCalamus Help.helpindex.
Aus dieser Datei holt sich der Apple Help Viewer seine Informationen über die Hilfe-Bücher Ihres Programms.
Für die anderen Sprachen müssen Sie nun die oben genannten Schritte wiederholen:
Die Offline-HTML-Seiten, die der Apple Help Viewer aus dem Programmpaket liest, müssen reine HTML-Seiten sein, die zwar CSS-Dateien einbinden können, aber ansonsten auf weiteren Luxus verzichten müssen. Machen Sie sich den Vorteil zunutze, dass der Apple Help Viewer eben auf Wunsch Online-Seiten von Ihrem Webserver bevorzugen kann. So können Sie Ihre Online-Seiten z.B. mit PHP- oder anderen Funktionen aufmotzen, so dass sie der Apple Help Viewer inklusive dieser Extras anzeigen kann wie jeder gewöhnliche Browser.
Da der Apple Help Viewer mit .php-Dateien nichts anfangen kann, müssen Sie, um PHP auch in .html- oder .htm-Seiten nutzen zu können, diese Dateiendungen auf Ihrem Webserver auch für den PHP-Parser anmelden. Wie das geht, verrät Ihnen Ihr ISP (Internet Service Provider). Oft laufen Webseiten auf einem Apache-Server, dessen httpd.conf-Datei entsprechend angepasst werden muss, damit der PHP-Parser auf dem Server eben auch .html- oder .htm-Seiten nach PHP-Code durchsucht und diesen ausführt.
Wir haben es bei uns zum Standard gemacht, normalen HTML-Seiten die Endung .html zu geben und PHP-fähige HTML-Seiten mit der Endung .htm zu sichern. So können wir zunächst mit UDO (s.o.) sehr schnell die fertigen reinen HTML-Seiten für das Programmpaket erzeugen. Anschließend tauschen wir über eine RegEx-Suche über alle .htm-Dateien hinweg den HTML-Kopf und HTML-Fuß der Dateien durch entsprechenden PHP-Code aus, um so z.B. PHPWebNotes in die Online-Seiten einzubinden. Dieses im Netz frei verfügbare Script bietet die Möglichkeit, Handbuchseiten online mit Kommentarmöglichkeiten zu versehen. Diese unschätzbare Funktion ist vielen Web-Programmierern sicher schon aus dem PHP-Online-Handbuch bekannt.
Ein Beispiel dafür ist – wie sollte es anders sein – unser iCalamus-Handbuch.