Monat: Dezember 2008

Ja, die Zeit der Anpassung ist da 😉

Mit dem OT kommt ja schon ein Satz an Texten mit Übersetzungen mit. Natürlich passen einem da so manche Texte nicht wirklich und man möchte sie ändern. Oder man möchte vielleicht noch Texte hinzufügen, so wie ich einen umfangreichen, firmenspezifischen Copyright-Text.

Ich habe hier bisher in der Not die Dateien in DITA_OT/xsl/common entsprechend geändert. Hat funktioniert, hat mir aber nicht so richtig gefallen, weil es eben Original-OT-Dateien sind, die ich editiere.

Daher fand ich das StringsPluginExample aus dem Files-Bereich der DITA-Yahoo-Group richtig genial und habe auch gleich versucht, das zu installieren (Anleitung). Man kann damit seine eigenen String-Dateien definieren, die dann die des OTs einfach überschreiben. Eigentlich eine einfache Sache…!

1. Leider ist nach der Installation beim Generieren einfach gar nichts passiert.
2. Irgendwann stellte ich fest, dass so ein Override erst ab Version 1.4.2 des OT möglich ist.
3. Kurz darauf versuchte ich bei meinem XMetal nach Anleitung ein OT-Upgrade durchzuführen (und zwar indem man die Variable DITA_OT_DIR auf das Verzeichnis der neuen version setzt). Hat nicht funktioniert.
4. Dann habe ich wieder festgestellt, dass dieser Parameter mit der OT-Version 1.4.2 nicht funktioniert, aber dass JustSystems einen Patch anbietet.
5. Mist, der Patch darf nur auf XMetal 5.1 angewandt werden. Und wenn man eine frühere Version hat, soll man doch bitte in Betracht ziehen erst einmal ein Upgrade von XMetal zu machen.

Kurz: ich mache alles wie bisher und kommentiere meine Änderungen brav. Allerdings finde ich es sehr bedenklich, dass ich ein Tool habe, mit dem ich nicht mal eben so ein Upgrade meiner Architektur durchführen kann. Klar, wenn ich nur in Notepad++ arbeite und über die Kommandozeile publiziere, ist das eher problemlos 😉

Ich frage mich, ob man das Problem z.B. auch mit Arbortext hat?

Klingt ja fast schon wie Spam:

Your life just got better.
Not in big ways. Your social life isn’t going to be helped, though with any luck you may now have more time for one.

Quelle: welcome.html der apache-ant-Installatiion

Die Zielgruppe ist ja wohl eindeutig. Immer diese Klischees, dass Entwickler kein soziales Leben haben… 😉

Jeder, der mit DITA anfängt, kommt schnell an dem Punkt an dem er das starke Bedürfnis hat, den Output an das eigene Layout anzupassen. Die Standardlayouts im OT sind, sagen wir mal, sehr nüchtern oder auch eher 0.5 als 2.0 😉

Und in einer Firma will man natürlich Logos und allerlei Schnick-schnack einbauen.

So, und ich will nun beginnen einen schönen XHTML-Output zu bauen und habe nun damit angefangen die XSL-Stylesheets auseinanderzunehmen, um zu verstehen, was eigentlich wo passiert.

Schöne Overrides

Sehr interessant fand ich diese schöne modulare (oh ja, das Wort das jeden technischen Redakteur jauchzen lässt!) Vorgehensweise die eigenen Anforderungen einzubinden. Robert Anderson zeigt in diesem Webinar, dass man eigene Anpassungen immer auslagern sollte, seien es eigene Spezialisierungen oder eben auch „nur“ eigene Layoutdefinitionen. So muss man beispielsweise später keine Bedenken haben, wenn man ein Upgrade auf eine neue OT-Version machen möchte: man hat eben keine Original-OT-Dateien bearbeitet, sondern nur eigene, die in die OT-Dateien nur eingebunden werden.

Das OT bietet dem User die Möglichkeit sogenannte Overrrides zu definieren, die die Standard-Einstellungen mit den selbst definierten überschreiben.  Diese Overrides werden in Plugins ausgelagert. In der Datei _dita2htmlImpl.xsl_ sind dafür ab Zeile 4166 Templates vorgesehen und zwar für Header, Footer, die head-section,Angaben zu CSS-Dateien und Skripten.

Eine sehr einleuchtende Vorgehensweise, die schön modular und damit leichter pflegbar ist.

Ich benutze ja XMetal und hier wurde eine solches Layoutmodul schon mitgeliefert. Wer einmal den Output Single HTML file advanced testet, wird sehen, dass da ein JustSystems-Design hinterlegt ist. Die entsprechenden Dateien findet man je nach Installation ungefähr hier: c:\Programme\Gemeinsame Dateien\XMetaL Shared\DITA_OT\demo\xhtmls.

Hässliche Overrides

Umso seltsamer fand ich, dass für einfache Anpassungen im OT-User-Guide ein ganz anderes Vorgehen geschildert wurde: einfach das XSL aus dem OT kopieren, entsprechend ändern und unter anderem Namen abspeichern. Und dann den Output über dieses eigene Stylesheet erzeugen (Quelle). Nun ja, klar das geht. Aber irgendwann wird es nahezu unmöglich sein herauszufinden, was Original-OT ist und was man selbst verbrochen hat. Und Updates sind dann sehr aufwändig.

Schön oder hässlich? – Kommt drauf an

So wie ich das bisher verstehe, ist „hässliche“ Variante erst sinnvoll, wenn ich den XHTML-Output komplett anders haben möchte. Dann verbiegt man sich komplett, indem man alle Änderungen in Overrides auslagert. Ich habe beim TWiki genau diese Erfahrung nämlich gemacht. Man kann dort die Default-Styles mit eigenen Styles überschreiben und den Rest übernehmen. Bei einem Update haben die selbstdefinierten Styles damals nicht mehr gut funktioniert, weil man sich in zu vielen Punkten auf Default-Styles verlassen hat und die aber beim Update signifikant verändert wurden.

Los geht’s

Bei mir wird leider nicht bei einigen „billigen“ Styleverbesserungen bleiben, sondern ich will strukturell auch einiges anders haben als im Standard-Output und daher versuche ich mal es in einem neuen Stylesheet auszulagern. Es wird spannend 🙂

Einen kleinen Haken hat die Angelegenheit!

Man sollte nicht aus Versehen das Verzeichnis löschen, das man als Logfile-Verzeichnis angegeben hat. Sonst bekommt man nämlich diese vielsagende Fehlermeldung beim Generieren!

Tja, ich wusste durch diese Meldung zwar, dass irgendetwas nicht gefunden wurde, aber was?! Nachdem ich mir anschaute, welche Verzeichnisse ich kurz vorher „aufgeräumt“ hatte, wusste ich Bescheid…

Wer also bei XMetal eine Fehlermeldung zur DitaRenditionsImpl bekommt und gar mit dem Error code -2,146828212, landet hoffentlich auf dieser Seite und erlangt die Erleuchtung. Meine Suche danach hat nämlich nichts ergeben 😉

Ich weiß nicht wie es anderen geht, aber bei meiner XMetal-Installation schlägt es fehl, wenn ich mir die die Output Logs anschauen will: There is no valid logfile.

Ganz beliebt, wenn das Generieren gerade nicht geklappt hat und man gerne auf Fehlersuche gehen würde – grummel!

Wenn man sich dann eine Weile auf die Suche macht, findet man dann das Logfile irgendwo in den Untiefen des Programmverzeichnisses, was ziemlich nervig ist.

Umso besser, dass mein Kollege herausgefunden hat wie man das Verzeichnis seiner Wahl für die Logfiles definieren kann, um sie schneller im Zugriff zu haben 🙂

1. Man wechsele in das Verzeichnis C:\Programme\XMetaL 5\Author\DITA\XACs\shared\ditaoptions\. (Je nachdem ob man XMetal hier natürlich installiert hat… *g*)
2. Man öffne die Datei XMAXDitaOptions.js.
3. Man kommentiere die Zeilen 110- 124 aus indem man /** davor setze und ein **/ dahinter:


/**var logDir = basePrintDir + "\\log";

var tmpDir = fso.GetSpecialFolder(2); //TemporaryFolder
if (tmpDir) {
if (!fso.FolderExists(tmpDir.Path+"\\XMetaL")) {
fso.CreateFolder(tmpDir.Path+"\\XMetaL");
}
if (!fso.FolderExists(tmpDir.Path+"\\XMetaL\\renditions")) {
fso.CreateFolder(tmpDir.Path+"\\XMetaL\\renditions");
}
logDir = fso.BuildPath(tmpDir.Path,"XMetaL\\renditions\\log");
}
if (!fso.FolderExists(logDir))
fso.CreateFolder(logDir); **/

4. Dann die folgende Zeile davor setzen und den Pfad entsprechend den eigenen Wünschen anpassen:

var logDir = "C:\\Eigene Dateien\\DITA\\XMetal\\Logfiles";

5. Dasselbe Prozedere nun für die Datei XMAUDitaOptions.js ab Zeile 116 ff vornehmen

Und ab jetzt sollten die Logfiles zumindest leichter auffindbar sein. Das Problem, dass man sie nicht direkt aus XMetal heraus öffnen kann, bleibt erst einmal ungelöst.