RE: [frameusers-de] Kontextsensitive Hilfe ausschließlich mit FM12 erzeugen (Microsoft HTML Help)
Gust, Dieter
From: frameu...@googlegroups.com [mailto:frameu...@googlegroups.com]
On Behalf Of sim...@froghouse.de
Sent: Sunday, April 05, 2015 7:14 PM
Cc: s.st...@itwh.de
Subject: [frameusers-de] Kontextsensitive Hilfe ausschließlich mit FM12 erzeugen (Microsoft HTML Help)
Hallo Simone,
Simone Stoerr hat geschrieben:
Ich versuche, unter ausschließlicher Verwendung von FrameMaker 12 eine kontextsensitive Microsoft HTML online Hilfe zu erstellen. Also kein RoboHelp und auch kein WebWorks Publisher.
Aus - mir - unerfindlichen Gründen sind die von mir in FM vergebenen TopicAliase in der generierten .chm Datei verschwunden und werden durch "erfundene" IDs ersetzt.
D. Gust: Zunächst einmal kann ich die beobachtete Thematik nur bestätigen und recherchiere gerade Antworten.
Als Zwischenstand kann ich nur auf Links verweisen, die sich mit dem Thema befassen:
http://www.wvanweelden.eu/articles/part/methods-calling-webhelp
http://www.grainge.org/pages/authoring/calling_webhelp/calling_webhelp.htm
http://www.grainge.org/pages/authoring/calling_webhelp/using_topic_ids.htm
http://www.techscribe.co.uk/ta/web-to-help.htm
http://blogs.adobe.com/techcomm/2007/10/generating_context_sensitive_h_1.html
Hier unten noch einmal die Testergebnisse von Simone und ein erstes Feedback:
Was habe ich getan?
1. Ich habe meine FM Dateien erzeugt und Marken vom Typ "Topic Alias" in den Überschriften vergeben. In Anleitungen habe ich gefunden, dass man dies über zwei Wege machen kann - a) über das "Speziell" Menü - Veröffentlichungsoptionen - CSH-Markierungen anwenden und b) über die simple Zuweisung einer Marke vom Typ "Topic Alias". Beide Wege habe ich ausprobiert - das Resultat ist identisch (jedenfalls sieht es in der FM Datei so aus).
Gust: Das Ergebnis muss identisch sein. Auf beide Arten wird der Custom Marker TopicAlias erzeugt.
Ich habe ausschließlich numerische IDs zugewiesen wie z.B. "2000" oder "4200". Das muss ich so machen, da ich die Hilfe komplett aus einer nicht funktionierenden alten Version neu erstellen muss - die Programme selber bleiben aber unverändert (und damit die IDs, die ja bereits "einprogrammiert" sind).
2. Ich habe eine Textdatei vom Typ .h erstellt - bezüglich des Formates basierend auf einer automatisch generierten .h Datei (projectname_!Generated!.h). Dies hatte ich ebenfalls in Anleitungen gelesen (FM online Hilfe). Der Inhalt dieser Datei sieht wie folgt aus:
#define 2000 2000 /* 4 Anwendungsoberfläche */
#define 2022 2022 /* 4.1.1 Menü Datei */
…
3. Ich habe die Microsoft HTML Hilfe publiziert. Es wurde erneut eine projectname_!Generated!.h Datei erzeugt. In dieser Datei werden meine vergebenen IDs nicht verwendet. Der Inhalt sieht wie folgt aus:
#define 2000 1
#define 2022 2
…
> D. Gust Zumindest die Inhalte der Custom Maker TopicAlias stehen automatisch drin (und das sollen wohl die „TopicIDs“
= TopicTitel sein) und nicht die „Map-Nummern die immer „nur“ numerisch sind
(geht aber in den meisten Diskussionen Kraut-und-Rüben-durcheinander)
(http://blogs.adobe.com/techcomm/2007/10/generating_context_sensitive_h_1.html)
so auch im Online Event mit Neil Perlin
https://www.adobe.com/cfusion/event/index.cfm?event=register_no_session&id=2455456&loc=en_us
WvanWeelden schreibt dazu: „When using id's, you assign a unique topic id and a unique Map number to
a topic or an anchor in a topic.
The Map number is a unique number ranging from 1 to 4,294,967.
The Map number is the id used for context sensitive help in CHM files and can also be used for WebHelp.”
FrameMaker erzeugt erzeugt immer, wie festgestellt, die .h Datei mit den Inhalten der TopicAlias Marker
und als 2. Spalte „dumme“ Map-Nummern von 1 ab hochzählend
Der Anwender „darf“ diese Nummern, so wie bei Dir umgesetzt, ersetzen durch Wiederholen der ersten Zahlenspalte (also die MapID/TopicID Spalte), diese erste Spalte sollen ja eigentlich sprechende Topic-IDs sein können (aber nicht sein müssen).
Wenn ich die generierte .chm Datei öffne und mir den Quellcode anzeigen lasse, wird hier noch eine ganz andere ID verwendet. Diese ID hat das Format CSH_1...n wobei die IDs einfach aufsteigend nummeriert werden:
Beispiel:
<p class="FM_Heading1"><a name="XREF_72066_13_Glossar"></a>Gloss<a name="CSH_1"></a>ar</p>
Was läuft hier schief? Warum verwendet FM12 meine zugewiesenen IDs nicht? Bzw. was mache ich hier falsch?
Was diese CSH_1 sollen, ist mir auch noch völlig unklar.
So viel kann ich schon sagen: Der Unterschied zwischen Map ID (TopicID?) und Map-Nummer(die ja selbst auch ein ID ist) in allen den meisten Dokumenten völlig diffus beschrieben,
weil deren Auswirkung in Verbindung der magischen „Online Help APIs“ oder „JavaScripts“ nicht dokumentiert ist.
Und auch die Antwort im Adobe Forum verstehe ich nicht:
„Nope, the first 2000 is what the programmers call – that corresponds to the 1, or 2 or 3, etc. that the MapID is assigning to the topics.
I’m not sure in the FM publish route where the link is made (or can be seen) to the resulting topics”
Und es wäre ja egal, wenn FM beide Zahlenspalten auf Wunsch identisch generiert, anstatt einfach bei 1 beginnend hochzuzählen.
Gruß
Dieter Gust
diete...@itl.eu
[itl]
AG
Elsenheimerstraße 65
D-80687 München
www.itl.eu
--------------------------------
Die nächsten itl-Seminare zur Technischen Dokumentation
Mittwoch, 17. bis Donnerstag, 18. Juni in München:
2-tägiges Seminar Textarme Dokumentation – zielgruppenorientiert und kostensparend mit Bildern arbeiten
www.itl.eu/termine/seminare-tagungen/17-06-15-muenchen-textarme-dokumentation.html
Mittwoch, 24. bis Freitag, 26. Juni in Stuttgart:
3-tägiges Kompaktseminar Technische Dokumentation
www.itl.eu/termine/seminare-tagungen/24-06-15-stuttgart-3-taegiges-kompaktseminar-technische-dokumentation.html
Mittwoch, 16. bis Freitag, 18. September in Hamburg:
3-tägiges Kompaktseminar Technische Dokumentation
www.itl.eu/termine/seminare-tagungen/16-09-14-hamburg-3-taegiges-kompaktseminar-technische-dokumentation.html
--------------------------------
Vorstandsvorsitzender: Peter Kreitmeier, Vorstand: Regine Ceglarek, Aufsichtsratsvorsitzende: Christine Wallin-Felkner
Handelsregister Amtsgericht München, HRB 135571, USt-IdNr. DE129390101
Simone Störr
vielen Dank für Deine Hilfe. Zwischenzeitlich hab ich es geschafft, die Hilfe mit den IDs zu erzeugen!
Der Aufbau meiner *.h Datei war schon richtig
#define 2000 2000 /* 4 Anwendungsoberfläche */
#define 2022 2022 /* 4.1.1 Menü Datei */
usw.
Allerdings hatte ich diese Datei nicht an der richtigen Stelle eingebunden. Das hatte ich in der Online-Hilfe von Adobe irgendwie übersehen. Die Datei muss also zwingend in demselben Ordner liegen wie die Framemaker-Dateien, die Grundlage der chm-Datei sind. Und die von Framemaker erzeugte (projectname_!Generated!.h) muss in jedem Fall von Hand nachgearbeitet werden (was ich mir damals einfach nicht vorstellen konnte…)
Herzliche Grüße
Simone Störr
--
--
Sie erhalten diese Nachricht, weil Sie Mitglied der Google Groups-Gruppe "frameusers-de" sind.
Für das Erstellen von Beiträgen in dieser Gruppe senden Sie eine E-Mail an
frameu...@googlegroups.com
Um sich von dieser Gruppe abzumelden, senden Sie eine E-Mail an
frameusers-d...@googlegroups.com
Für Nachrichten an den »Eigentümer« der Gruppe, senden Sie eine E-Mail an
frameuser...@googlegroups.com
Weitere Optionen finden Sie in dieser Gruppe unter
http://groups.google.com/group/frameusers-de?hl=de
---
Sie erhalten diese Nachricht, weil Sie in Google Groups E-Mails von der Gruppe "frameusers-de" abonniert haben.
Wenn Sie sich von dieser Gruppe abmelden und keine E-Mails mehr von dieser Gruppe erhalten möchten, senden Sie eine E-Mail an frameusers-d...@googlegroups.com.
Weitere Optionen finden Sie unter https://groups.google.com/d/optout.
r...@commatec.de
Die Kritik an der diffusen FrameMaker Dokumentation teile ich voll und ganz.
Die Sache mit den IDs an sich ist aber nicht so komplex und verwirrend, wie sie erscheint.
1. Software fragt üblicherweise nach einer Zahl, wenn ein Hilfethema kontextsensitiv aus einer Microsoft HTML Help-Datei aufgerufen werden soll. Dieser Zahlenwert wird als „ID“, „Help ID“, „Map ID“, „Map Number“ , „Context ID“oder wie auch immer bezeichnet.
2. Redakteure sollen Stellen in ihrem Dokument kennzeichnen, die von der Software „angesprungen“ werden. Manche Softwareentwickler gehen davon aus, dass Redakteure in der Lage sind, eine Zahl an irgend eine Überschrift zu pappen, sie jederzeit wiederzufinden, sich wie von selbst daran zu erinnern, wo genau sie eingefügt wurde und sogar aus welchem Grund. Wer bereits das Vergnügen hatte, mehrere Tausend IDs in einer umfangreichen Dokumentation zu verteilen, der weiß, dass der Mensch sich anhand von Zeichenketten besser orientieren kann als anhand von Zahlenwerten. Stellt der Redakteur sich geschickt an, dann entwickelt er ein System, mit dem er seine Einsprungmarken in den Topics verwaltet. Anstelle einer Zahl gibt er besser eine Zeichenkette ein, die ihm über den Inhalt und die Bedeutung dieser Stelle etwas sagt. So eine „sprechende ID“ nennt man einen „TopicAlias“.
3. Damit beide Welten (Mensch und Maschine) zueinander finden, benötigt man eine Übersetzungstabelle. Wenn Softwareentwickler und Redakteure zusammenarbeiten, dann entsteht eine für beide Seiten sinnvolle Datei. Auf der einen Seite steht eine Zahl (von und für die „Maschine“), auf der anderen Seite eine Zeichenfolge (für den Redakteur). Diese Tabelle bildet fortan die Schnittstelle zwischen Softwareentwicklung und Dokumentation. Ändert sich in der Software aus irgend einem Grund im Laufe der Entwicklung eine Zahl (Help ID), dann braucht der Redakteur nur eine Korrektur an der Übersetzungstabelle vornehmen und muss nicht in seinem Dokument etwas ändern. Das Nachvollziehen von Änderungen bei Updates (Welche Zahlen sind neu, welche sind weggefallen?) ist so auch möglich. Zu Zeiten, als man gerne Dialog für Dialog beschrieb, gab es eine Funktion in C++, die TopicAliasse aufgrund von Ressourcennamen aus der Software automatisch generierte. In C-Syntax hieß das, es wurde eine Zeichenkette als Konstante definiert und dieser Konstanten eine Zahl zugewiesen z. B.:
#define HID_Start_Screen 5
4. Der Inhalt dieser Übersetzungstabelle (in Form einer Konstantendefinitionsdatei mit der Endung .h) wird für die Software mitkompiliert und genauso wird sie im Hilfesystem hinterlegt. Umgangssprachlich formuliert: Die Software sagt „5“ und das Hilfesystem versteht „HID_Start_Screen“, sucht die entsprechende Stelle, an der der Autor diesen „TopicAlias“ eingefügt hat, und zeigt das Thema an. „Unter der Haube“ passiert – man ahnt es – etwas mehr. Im CHM-Format ist nicht nur vorgesehen, dass man bei Bedarf mehrere .h-Dateien mitkompilieren kann. Man kann auch weitere Aliasse schaffen. Letzteren Mechanismus des „doppelten Mappings“ macht sich FrameMaker/RoboHelp zu Nutze, damit man Marken vom Typ „TopicAlias“ in FrameMaker mit für Menschen lesbaren und verständlichen Zeichenketten füllen kann und im Output schließlich Sprungadressen auf Anker in HTML-Dateien bekommt, ohne zu wissen, wie letztere schlussendlich heißen werden.
5. Es gibt mehrere Möglichkeiten, wie man die Übersetzungsdatei für den im FrameMaker 12-Prozess erstellen kann.
a) FrameMaker 12 generiert IMMER eine .h-Datei, füllt diese mit den vorhandenen TopicAlias-Marken, zählt diese von 1 beginnend durch, nennt sie genauso, wie das verwendete FrameMaker-Buch, hängt an den Dateinamen „_!Generated!.h“ an und kopiert sie in den Ordner, den man als Ausgabeort beim Publishing angewählt hat. Auf Basis dieser Datei könnten Softwareentwickler nun ihre „Zahlen“ in die Ressourcen eintragen. Die generierte .h-Datei kompiliert der FrameMaker 12 Prozess in die CHM. Fertig. – Das ist praxisuntauglich und wird nicht geschehen. Also kann die von FrameMaker generierte .h-Datei nur zu QM-Maßnahmen ausgewertet werden, z.B. um festzustellen, welche TopicAliasse in FrameMaker eingegeben wurden und ob nicht versehentlich doppelte oder mit welche mit Tippfehlern vorhanden sind.
b) Die Softwareentwickler erzeugen automatisch eine Datei mit sinnvollen Zeichenketten als TopicAliasse, die die Autoren inhaltlich einordnen können. Diese .h-Datei wird in den Ordner kopiert, in dem sich das FrameMaker-Buch befindet und bekommt denselben Namen wie das Buch. Handbuch.book -> Handbuch.h. Wenn der FrameMaker 12-Publishing-Prozess so eine Datei findet, dann kompiliert er diese Datei anstelle der von ihm selbst generierten in die CHM.
6. Die von FrameMaker/RoboHelp generierten Dateien finden sich üblicherweise im Ordner %USERPROFILE%\AppData\Local\Temp\TPUBTMP. Einige Dateien sind in diesem Ordner nur so lange vorhanden, solange man den Dialog „Publish Result“ in FrameMaker nach dem Anstoßen des Publishing-Prozesses noch nicht wieder geschlossen hat! Wechselt man dann in den Explorer und öffnet die Datei TPubTemp.hhp in einem Texteditor oder mit dem Microsoft HTML Help Workshop, dann sieht man ganz unten in der Datei zwei Abschnitte: [ALIAS] und [MAP]. In beiden steht ein Dateiverweis.
7. [MAP]: Dort ist die verwendete *.h-Datei eingetragen. Wenn dort die von FrameMaker generierte Datei eingetragen ist (…_!Generated!.h), dann fehlt die selbst angefertigte bzw. angepasste *.h-Datei im Ordner des FrameMaker-Buches.
8. [ALIAS]: Dort ist der Verweis auf eine xml-Datei mit der Endung .ali eingetragen, die jedes Mal neu generiert wird. Darin steht das „Mapping“ zwischen TopicAlias-Marker und HTML-Anker. Diese Datei kann sich ändern, wenn Parameter im Konverter geändert werden. Für die Praxis und Bedienung hat diese Datei keine Relevanz. Kein Autor oder Entwickler kommt direkt mit ihr in Kontakt. Wenn man sich diese Datei ansieht, klärt sich aber, warum FrameMaker 12 jene „CSH_*“-Werte zusätzlich generiert und verwaltet. Sie dienen offenbar dazu, eindeutige Sprungziele zu erzeugen, wenn dieselbe Überschrift für 2 verschiedene Topics im Dokument vorkommt und die HTML-Datei-Benennung auf Basis der Überschrift generiert werden soll. (Andere Konverter verwenden dazu die interne Absatznummer in FrameMaker oder generieren Zufallszahlen und fügen sie hinzu.)
9. Noch eine Lücke in der dokumentation von FrameMaker 12 fällt auf. Die Gestaltung von Hierarchien im Inhaltsverzeichnis (TOC) ist abhängig von den Formatierungen im FrameMaker TOC. Die RoboHelp-Entwickler haben dazu einst Regeln in ihrer Software hinterlegt, die nirgends in der Dokumentation von FrameMaker 12 zu finden sind: Inhaltseinträge mit größerer Schrift werden als in der Hierarchie höher interpretiert. Fette Schriftzeichen in Absatzformaten werden höher eingestuft als nicht fette. Eingerückte sind niedriger als solche ohne Einrückung. – Diese Logik gehört meiner Meinung nach auf den Prüfstand oder besser auf den Müll. Benutzerfreundlicher wäre eine Lösung nach dem Vorbild des Webworks ePublishers, nämlich jedem Absatzformat, bei dem eine neue HTML-Seite ausgegeben werden soll, einen Wert für die Hierarchie im Inhaltsverzeichnis manuell zuweisen zu können.
Fazit:
Mit FrameMaker 12 kann man ordentliche CHM-Ausgaben realisieren. Die Einrichtung des Settings wäre auch für Einsteiger kein Problem, wenn Adobe endlich etwas an der Qualität (und besonders an der Informationstiefe) der Dokumentation von FrameMaker 12 tun würde.
Nebenbei erwähnt ist es schon blamabel, wenn ausgerechnet dieses Adobe-Produkt in seiner Online-Hilfe Screenshots zeigt, die eine so grottenschlechte Qualität haben, wie ich sie seit Jahren nirgendwo sonst gesehen habe. So ziemlich alle Fehler, die man bei der Konvertierung von Screenshots begehen kann, wurden dabei konsequent begannen.
Ich hoffe, etwas zur Erhellung der FrameMaker 12 Abgründe beigetragen zu haben.
Grüße von Ralf Klossek
-------------------------------------------------
Ralf Klossek (Dipl.-Ing. FH)
-------------------------------------------------
commatec
Ing.-Buero fuer Technische Dokumentation
Ludwigstr. 51
D-35390 Giessen
-------------------------------------------------
Gust, Dieter
Hallo Ralf,
Glückwunsch. Endlich hast du uns FM-Motorhaube geöffnet, und ich denke dass Puzzle bekommt langsam ein Gesicht.
Dennoch hat FrameMaker offenbar 2 CSH-Motoren (CSH = Kontextsensitive Hilfe) und mir fehlen noch einige wichtige Details.
Diese Details folgen nun:
In Anlehnung an Deine Nummerierung hier erst einmal 0.
0. Der Sprung auf einen Topic ist für das Anzeigesystem Internet-Browser oder HTML-Help immer eine URL
Damit aus einer Applikation ein bestimmtes Topic der Hilfe aufgerufen werden, kann gibt es also nur 1 Lösung:
Der Browser (auch in HTML-Help steckt ja ein HTML-Browser) benötigt diese eindeutige URL zum Topic.
Die URL ist eine Pfadangabe auf die HTML-Datei, in der das Topic steckt.
0. A) Bei einer HTML5-Hilfe ist die URL der absolute Dateipfad auf das HTML-Topic
Zum
Beispiel file:///C:/Users/dieter.gust/Documents/Test/Manualx/topic.html
Weil die Topics auch in der HTML5-Hilfe nicht isoliert herumstehen, sondern ein Gesamtkonzept bilden, und der eigentliche Topic-Dateiname sich auch
noch bei jeder Konvertierung dynamisch ändern kann, benötigt man einen fixen Einstiegsanker, der sich nie ändert, und die tatsächliche URL sieht komplizierter aus:
Beispiel: file:///C:/Users/dieter.gust/Documents/Test/Manualx/index.html#t= HTMLManual/Introduction/Introduction.htm%23TOC_3_3_Cleaningbc-3&rhtocid=_3_2
Der Topic-Pfad ist als Anker definiert und zwar als relativer Pfad zur Basis-HTML-Datei (hier index.html) und wird durch einen besonderen Prozess erst generiert.
0.B) Bei CHM sähe das aber so aus: Helpfile.chm::/Topic.htm (vgl. https://msdn.microsoft.com/en-us/library/windows/desktop/ms524236(v=vs.85).aspx)
Zunächst gilt: Man könnte also ganz ohne MapIDs und Mapnumber (letzteres im Folgenden Map# genannt) arbeiten.
MapIDs oder Map# sind im HTML-Konverterprozess als „Umweg“ eingeführt, um dann über eine Zuordnungstabelle (Mapping-Table) erst die Zuordnung zur
konkreten Topic-URL zu erhalten.
MapIDs oder Map# sind im Prinzip alternativ verwendbar, aber man darf beide Benennungen nicht durcheinander bringen(!), weil FrameMaker beide unterschiedlich verwendet.
Der Umweg MapID oder Map# entkoppelt also „nur“ die Applikation von der sich möglicherweise änderbaren URL eines Topics.
Aber noch einmal: Die eigentliche Zuordnung auf die Topic-URL muss nach wie vor existieren, nun jedoch über eine irgendwie zu erzeugende und irgendwo vorhandene Mapping-Table aus MapID/Map# und Topic-URL.
Ob historisch bedingt oder warum auch immer, man kann das Spielchen doppelt indirekt treiben:
Man definiert in der Applikation die Map# ordnet wo auch immer der Map# eine sprechende MapID (dann gerne auch „TopicID“ genannt) und erst der TopicID
die konkrete URL bzw. den HTML-Dateinamen des Topics zu. Aber genau hier bei der doppelten Zuordnung macht FrameMaker nur noch „sehr beschränkt mit“.
Und überhaupt, der generelle Prozess braucht nur eine Zuordnung aus der Applikation zum gewünschten Topic, ob MapId oder Map# genannt.
Ergänzung bzw. Anhang zu Ralfs Erklärungen
Nun gut, wer erzeugt die Mapping Table und stellt die .h-Datei die einzige Mapping-Table dar? Kurze Antwort Nein!
Verlassen wir den generischen Teil einer kontextsensitiven Hilfe und fragen, was der FrameMaker anbietet:
Der Anwender muss ja irgendwo mitteilen, dass eine MapID oder eine Map# (definiert auf Seiten der Applikation) zu einem bestimmten Topic gehört.
Dafür bietet FrameMaker den Marker „TopicAlias“ an: Der Anwender fügt den Marker an die Stelle in seinem FrameMaker-Dokument ein, auf die ein konkreter Einsprung aus der Applikation zeigen soll. Und der Einsprungpunkt ist im Prinzip die MapID oder Map#, von der wir oben gesprochen haben.
Jetzt kommt das Problem: In FrameMaker gibt es nur den Markentyp TopicAlias und für FrameMaker ist das die MapID. Für die doppelte indirekte Zuordnung Map# über nun auch gern „sprechende MapID genannt“ (und so auch gern TopicID genannt) zur URL, dafür hat FrameMaker nur folgenden Ansatz: Er erzeugt z. B. automatisch die .h.-Datei als Mapping-Table, bei der er brav alle Inhalte der TopicAlias-Marker in die erste Spalte listet (und als MapID interpretiert!!) und erzeugt die Map# bei 1 beginnend und automatisch hochzählend.
Wenn der App-Entwickler sagt, ich nenne dem Hilfe-Autoren den Einsprungpunkt „4711“ dann kann der Hilfe-Autor diese Nummer bei FM in einen TopicAlias-Marker eintragen und am Anfang einer Überschrift einfügen und so die Zuordnung zwischen Einsprungpunkt und Topic festlegen. FM trägt die Nummer aber als „sprechende“ MapID (TopicID) in die erste Spalte der .h Datei ein und erzeugt zu jedem Eintrag eine fortlaufende Map# bei 1 beginnend. Wenn der Applikationsentwickler mit seiner Sprungadresse auf die Basisdatei index.html verweist und als Identifikation die Map# mitgibt (die er im Beispiel 4711 genannt hat) dann versteht der FrameMaker-Prozess „nur Bahnhof“, weil der geht von einer MapID 4711 aus und bietet als Map# dazu z. B. seine laufende Nr. z. B. „ 1“ an.
Als Workaround für bestimmte Hilfekonzepte, etwa CHM aber nicht für die HTML5-Hilfe(!) kann der Anwender offenbar in der .h-Datei nun händisch (bäh!) die lfd. Nummer ersetzen durch die Nummer ersten Spalte:
Beispiel:
FrameMaker generiert:
#define 4711 1
#define 4712 2
Der Anwender macht daraus
#define 4711 4711
#define 4712 4712
Offenbar nutzt ein Post-Prozess für CHM-Generierung die von FrameMaker generierte untaugliche .h-Datei.
In 5 b sagt Ralf:
b) Die Softwareentwickler erzeugen automatisch eine Datei mit sinnvollen Zeichenketten als TopicAliasse, die die Autoren inhaltlich
einordnen können. „Diese .h-Datei wird in den Ordner kopiert, in dem sich das FrameMaker-Buch befindet und bekommt denselben Namen wie das Buch. Handbuch.book -> Handbuch.h.
Wenn der FrameMaker 12-Publishing-Prozess so eine Datei findet, dann kompiliert er diese Datei anstelle der von ihm selbst generierten in die CHM.
So hab ich Ralf verstanden und so hat es wohl Simone gemacht.
Was wäre aber, wenn der Applikationentwickler sein Einsprungadressen-Konzept ändert und statt Map# MapId sagt? Dann müsste doch alles ohne Editieren der .h-Datei klappen.
Und was ist mit HTML5-Hilfen
Für eine HTML5-Hilfe ist das Editieren oder die Zurverfügungstellung einer.h-Datei irrelevant.
Da gibt’s nach der HTML-Generierung kein Postprocessing und die .h-Datei wird nicht verwendet.
Bei der HTML5-Hilfe stellt ein generiertes JavaScript die Zuordnung zwischen TopicAlias-Marker-Inhalten und Topic-URL her.
Das JavaScript wird über die index.html geladen.
Die JavaScript-Datei ist im Output-Unterordner whxdata: csh.js
Beispiel-Einträge in dieser Datei:
<item mapid=\"24711\" mapnum=\"1\" topicurl=\"Manualx/Chapter3/SystemRequirements.htm#CSH_2\" />
<item mapid=\"147114\" mapnum=\"2\" topicurl=\" Manualx/Chapter2/SafetyInstructions/SafetyInstructions.htm#CSH_1\" />
Ein Testaufruf mit folgenden Parametern im Browser bestätigt die Verarbeitung:
a) <output-path>/index.html?rhcsh=1&rhmapno=<mapnumber>
oder:
b) <output-path>/index.html?rhcsh=1&rhmapid=<mapid>
Da FrameMaker die mapnumber (=Map#) selbst erzeugt, muss der App-Entwickler in seiner Applikation den Aufruf b) hinterlegen
Ach ja und die Anker #CSH_1 usw. sind wohl dazu da, irgendwo mitten in einen Topic springen zu können und erzeugt FM pauschal automatisch.
Und dann klappt’s auch mit den Nachbarn aus Applikation und Hilfe, oder?
Ach ja Ralf stellt dann noch fest:
Noch eine Lücke in der Dokumentation von FrameMaker 12 fällt auf. Die Gestaltung von Hierarchien im Inhaltsverzeichnis (TOC) ist abhängig von den Formatierungen im FrameMaker TOC.
FrameMaker erzeugt nur dann verlässliche HTML-Navigationsbereiche (TOCs) wenn man von einem Buch mit TOC ausgeht. Dann übernimmt er für die HTML-konvertierung das TOC.
Leider gibt es so keine mögliche buchübergreifende-Konvertierung, also mehrere Bücher und Gruppierungen oder Ordner im Masterbuch festelgen und die Struktur in die Navigationsstruktur mit abbilden. Das wäre toll. …
Dieter Gust
Aufsichtsrat, Leitung Forschung & Entwicklung
itl AG, München
Telefon: +49 89 892623-600
r...@commatec.de
Hallo Dieter,
mein Text bezog sich ausschließlich auf FrameMaker 12 und seine CHM-Ausgabe (was ja der Anwendungsfall von Simone war).
Bislang hatte ich leider noch keinen Anlass und keine Gelegenheit die HTML 5-Ausgabe von FrameMaker 12 zu untersuchen.
Jetzt schon.
Zu Dieters 0.:
So isses.
Zu Dieters sonstiges 0 (Teil A und B) ein paar Ergänzungen und Konkretisierungen:
FrameMaker 12 generiert für jedes Dokument in einem Buch einen separaten Ausgabe-Ordner mit HTML-Dateien. So entsteht gemäß den Einstellungen, die der Anwender vorgenommen hat, für jedes Topic eine HTML-Datei in verschiedenen Unterordnern. Die Ordner-Struktur und Ablage der HTML-Dateien innerhalb einer mit FrameMaker 12 erzeugten CHM-Datei sieht übrigens ähnlich aus wie bei HTML 5. Einfach mal mit 7-zip eine CHM-Datei direkt öffnen und hineinsehen.
Mithilfe der Datei index.html werden in HTML 5 die verschiedenen Komponenten des Hilfesystems im Browser zusammengebaut. Eine Anzahl von eingebundenen JavaScripts reagiert auf unterschiedliche Übergabeparameter und realisiert so die üblichen Funktionen eines Hilfesystems.
Bei CHM fehlt diese Datei. Sie ist dort unnötig. Es ist die Aufgabe des HTMLHelp-Viewers neben dem eigentlichen HTML-Inhalt das Inhaltsverzeichnis, den Index, die Suchfunktion usw. anzuzeigen. (Für die Anzeige der HTML-Seiten werden Bibliotheken des Internet-Explorers genutzt, weshalb man üblicherweise mit großen Kompatibilitätsproblemen kämpfen muss, wenn man nicht weiß, welche Version des IE auf dem Zielsystem der CHM-Datei vorhanden sein wird. Und dann wären da noch die standardmäßig aktivierten Windows-Sicherheitseinstellungen, die CHM auf Netzwerklaufwerken ohne administrativen Eingriff erst einmal unbrauchbar machen … anderes Trauersp... äh Thema.
Wie ist es nun mit dem technischen Umsetzung eines kontextsensitiven Hilfesystems?
In den Entwicklungsumgebungen von Microsoft kann man auf mehrere Arten auf Inhalte in CHM-Dateien zugreifen.
Der von Dieter zitierte Aufruf (die Info auf der Microsoft-Seite) zeigt die simpelste Möglichkeit.
Wer einen sinnvollen Mapping-Mechanismus verwenden will, der muss als Software-Programmierer in den gängigsten Entwicklungsumgebungen erst einmal ein paar Funktionen zusätzlich schreiben. Einen Einblick in die grundsätzlichen Möglichkeiten zur Implementierung von CHM in eine Applikation hat Adobe – man staune - mitgeliefert.
C:\Program Files (x86)\Adobe\AdobeFrameMaker12\fminit\Publisher\HtmlHelp\Inc\HtmlHelp.h
Wie die Programmierer die Übersetzung ihrer Zahlen in Zeichenketten realisieren (sei es über .h-Dateien oder irgend eine XML-Struktur), ist für den Technischen Redakteur eigentlich irrelevant. Man sollte sich als solcher nur nicht wundern, dass vielen Softwareentwicklern die technischen Basics zur Anbindung eines Hilfesystems an eine Applikation unbekannt sind. Sie möchten am liebsten einmalige und unveränderliche HTML-Dateinamen verwenden. Es gibt nicht viele Programmierer, die sich mit Online-Hilfesystemen gut auskennen. Üblicherweise heißt es: „Und jetzt noch die Doku, am besten Windows-Standard.“ – Aber was ist das? Es gibt seit WinHelp keinen solchen Standard mehr.
Was bedeutet das für die Praxis mit FrameMaker 12?
Das Konzept des FrameMaker 12 Publishing Prozesses scheint sich mit den Vorstellen der Softwareentwickler nicht zu vertragen.
Grundsätzlich kann die Empfehlung nur sein, immer eine Mapping-Tabelle als Schnittstelle zwischen Entwicklung und Doku zu verwenden und die Anwendungsentwickler zu überzeugen, dass Autoren keine Zahlen oder HTML-Dateinamen in ihre Quelldokumente hinterlegen sollen. Die Autoren sollten unbedingt mit Zeichenketten arbeiten und Zahlen nicht anfassen müssen. Der Prozess zur Erzeugung dieses Mappings muss einmalig auf Entwicklerseite eingerichtet werden. Mit jedem Release kann dann eine aktuelle „Mapping-Tabelle“ an die Technische Redaktion ausgeliefert werden. Schon ist nebenbei auch klar, was neu ist, was weggefallen ist, was sich geändert hat. Im Laufe der Zeit werden die Zeichenketten zu immer besseren Orientierungspunkten für die Redakteure im Projekt.
Beispielhafter Ausschnitt aus einem realen Projekt.
Hier wurde aus den Ressourcennamen der Software Zeichenketten generiert, aufgrund derer die Autoren die einzelnen Screens bereits identifizieren können ohne eine spezielle Funktion in der Software zu benötigen, die die von der Software aufgerufenen Zahlen anzeigt.
Es bedeuten:
HID -> Abkürzung für HelpID (zur Kennzeichnung der Art der Konstanten)
_D -> Dialog
_MU -> ein Hauptbereich innerhalb der Software
_xx -> der Screen an sich
Zahl -> das ist der Aufrufparameter aus der Software, den der Autor niemals anfassen muss.
Im Kontext sieht es wie folgt aus und befindet sich in einer .h-Datei, die – wir sagen jetzt einfach mal „auf irgend eine Weise“ - von der Software für den Aufruf des Hilfesystems verwendet wird. Sie wird in den Ordner gelegt, in dem auch das FM12-Buch liegt und so benannt, wie das FM-Buch heißt, z.B. Manual.book -> Manual.h:
#define HIDD_MU_UnitChgLayout 161188
#define HIDD_MU_UnitConfigChangeUnitSet 131270
#define HIDD_MU_UnitConfigCTestAssign 200174
#define HIDD_MU_UnitConfigETestAssign 131325
#define HIDD_MU_UnitConfigTestAssign 131526
#define HIDD_MU_UnitConfigUnitSetting 131528
#define HIDD_MU_UnitConfigUnitTypeChange 200135
Die Zeichenkette beginnend mit HIDD… ist der Wert, der vom Redakteur nur an einer einzigen Stelle im gesamten Buch in eine TopicAlias-Marke geschrieben wird. Diese Marke wird am besten in eine Überschrift eingefügt, die ein neues Topic beginnen lassen soll - und am Ende der Überschrift (nicht unbedingt am Anfang, wie in der FM Doku empfohlen wird), damit der Übersetzungsprozess mit einem TMS nicht gestört wird. Soll ein Topic von mehreren Screens aus aufgerufen werden, dann werden mehrere TopicAlias-Marken ans Ende derselben Überschrift eingefügt.
Ich verwende immer den Begriff Topic-Alias, denn alle anderen Benennungen – MapID, HelpID, etc. - sind meiner Meinung nach nicht eindeutig. Sie werden mal so, mal so verwendet und selten direkt verstanden. Jeder Toolhersteller braut da seine eigenen Begrifflichkeiten zusammen. Am Ende ist die Verwirrung groß, wie man sieht.
Dieter wies bereits darauf hin, dass die FrameMaker-Inder zwischen MapNum und MapID unterscheiden, wobei MapID das ist, was in den TopicAlias-Marken eingefügt werden soll. MapNum und MapID sind untaugliche Begriffe, wie ich finde. Ja. sie tauchen in der von FM 12 generierten csh.js auf. Es sind also rein softwaretechnische Bezeichner, die niemals in die FrameMaker-Dokumentation hätten gelangen dürfen! Der Begriff CSH-Marker (CSH=content sensitive help) wird in der FM-Doku verwendet und im gleichen Satz wieder als TopicAlias-Marker bezeichnet. Alles sehr verwirrend für den Erstleser.
Wer nachlesen möchte: In der Online Hilfe von FM 12 der Abschnitt: Editing content -> Markers -> Publishing options -> Content-sensitive Help marker
Dieter schrieb: „Als Workaround für bestimmte Hilfekonzepte, etwa CHM aber nicht für die HTML5-Hilfe(!) kann der Anwender offenbar in der .h-Datei nun händisch (bäh!) die lfd. Nummer ersetzen durch die Nummer ersten Spalte“
Nein, das ist ein Missverständnis. Die Vorgehensweise von Simone ist nicht zu empfehlen. „Technisch“ funktioniert es zwar, aber so wird niemand ernsthaft arbeiten wollen. In der Praxis ist das oben beschriebene Verfahren (Paar aus Zeichenkette und Zahl) unbedingt vorzuziehen.
Wie geht man vor?
Die traditionellen Help-Tools (RoboHelp, DocToHelp, MadCap etc) erzeugen „Topic-Aliasse“ meist aus der Überschrift, die der Autor gerade als Topic Titel eingegeben hat. Sie haben die Sicht, dass der „Content“ mit einer Zeichenkette gekennzeichnet werden soll. Für den FrameMaker-Workflow ist es anders günstiger. Der Gegenstand der Beschreibung (z.B. ein Screen, von dem aus die Doku aufgerufen werden soll) wird mit einer Zeichenkette gekennzeichnet, dem eindeutigen TopicAlias. Vor gut 2 Jahrzehnten erstmalig in FrameMaker mit dem WebWorks-Publisher (heute: ePublisher) eingeführt und angewendet. Aus dieser Ecke kommt auch das Prinzip der TopicAlias-Marken in FrameMaker. ( … es ist alles nur geklaut … ) Wer also Dokumente besitzt, die für den ePublisher vorbereitet wurden, kann nun ohne diesen mit FM 12-Bordmitteln ohne große Umbaumaßnahmen publizieren.
Dieter schrieb: „Offenbar nutzt ein Post-Prozess für CHM-Generierung die von FrameMaker generierte untaugliche .h-Datei.“
Nein, das macht FrameMaker nicht. Der CHM-Compiler ist der für CHM notwendige Post-Prozess. Dieser bettet (in der in FM 12 implementierten Variante) immer eine .h-Datei ein: standardmäßig die von FrameMaker generierte .h-Datei (z. B. wenn gar keine Kontextsensitivität gefordert wird) oder eben jene .h-Datei mit dem Namen des FrameMaker-Buches, die im selben Ordner wie das Buch liegt und vom Redakteur dort hinterlegt wurde - wenn sie denn dort vorhanden ist.
Was ist mit der HTML 5 Ausgabe?
Wenn man eine .h-Datei mit dem Namen des FM-Buches in den Buch-Ordner legt, dann wertet auch der HTML 5-Publishing-Prozess diese „Mapping-Tabelle“ aus.
Microsoft HTML Help, WebHelp, Respsonsive HTML5, diese drei Formate werden unterstützt.
Wenn man die obige Beispiel-h-Datei so benennt wie das FrameMaker-Buch, und die Datei in denselben Ordner legt wie das FrameMaker-Buch, dann erzeugt der HTML 5-Publishing-Prozess von FrameMaker folgende csh.js:
<?xml version=\"1.0\" encoding=\"utf-8\" ?>
<csh-info>
<item mapid=\"HIDD_MU_UnitChgLayout \" mapnum=\"161188\" topicurl=\"Manual/Operation/Bedienung.htm#CSH_1\" />
<item mapid=\"HIDD_MU_UnitConfigChangeUnitSet \" mapnum=\"131270\" topicurl=\"Manual/Operation/Ultraschallelektronik_bedienen.htm#CSH_2\" />
…
</csh-info>";
Beides,
- mapid (= einmal festgelegter und eingegebener TopicAlias-Markentext)
und
- mapnum (Zahl, die die Applikation für einem Hilfeaufruf in sich fest verankert hat),
werden aus der .h-Datei übernommen und in diese XML-Struktur übertragen, die für HTML 5 als Schnittstelle zur Applikation dient.
Also kann eine Applikation beide Aufrufe verwenden:
- <output-path>/index.html?rhcsh=1&rhmapno=<mapnumber>
- <output-path>/index.html?rhcsh=1&rhmapid=<mapid>
Den Parameter “rhcsh=1&” kann man übrigens auch weglassen:
- <output-path>/index.html?rhmapno=<mapnumber>
- <output-path>/index.html?rhmapid=<mapid>
Funktioniert auch.
Grüße von Ralf