Die Redakteuse

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.

So lautete eine Google-Anfrage, die schließlich zu meinem Blog führte… *g*

Tja, ich würde sagen, man kann einiges damit anfangen: zum Beispiel studieren und einen Master und Bachelor als technischer Redakteur machen 😉

Und außerdem ist das Jobangebot in diesem Berufszweig gerade nicht das schlechteste, was ja schon einmal ein guter Ansporn sein kann.

So, ich habe nun eine tolle Ordnerstruktur.  Beim Schreiben mit DITA produziert man viele, viele Topics, also ganz viele einzelne Dateien. Diese Arbeitsweise ist geradezu prädestiniert dazu, die Arbeit auf mehrere Redakteursschultern zu verteilen.

Tja, und was sagt man gerne über viele Köche und ihren Brei? Ja, man muss die Zusammenarbeit irgendwie steuerbar und kontrollierbar halten. Wenn man nun kein CMS hat, um einem die Verwaltungsarbeit abzunehmen, sollte man zumindest eine Sache auf jeden Fall verfolgen:  Versionsverwaltung. Und damit meine ich keine täglichen Kopien des Arbeitsordners auf irgendein Laufwerk! Das nimmt auf die Dauer zuviel Speicherplatz ein und man hat bei mehreren Autoren keinen Überblick wer was wann editiert hat. Ein paralleles, effizientes Arbeiten ohne Versionsfehler ist dann wirklich schwer.

SubVersion (SVN) – eine kurze Einführung

Hier kommt nun SVN in Spiel.  SVN ist eine Open-Source-Software mit der man die Versionen von Dateien und Ordner verwalten kann. Sie kommt vor allem in der Software-Entwicklung zum Einsatz. Jede Änderung einer Datei / eines Ordners wird in einer Version festgehalten, so dass man auch immer wieder auf alte Versionen zurückgehen kann, falls man in der neuen nur Müll produziert hat. Zudem kann über die Versionshistorie auch verfolgen, welche Änderungen gemacht wurden, wer sie wann gemacht hat und, wenn es Kommentare gibt, auch warum.

SVN funktioniert so, dass man ein zentrales Verzeichnis hat, in dem die allgemein gültige Version der verwalteten Inhalte steckt, in meiner Branche also  die DITA-Dateien.  Das ist das sog. Repository.

Nun kann sich jeder, sofern Zugriffsrechte vorhanden, eine lokale Arbeitskopie dieses Repositories auf seinen Arbeitsplatzrechner ziehen (auschecken) und anfangen daran zu arbeiten. Das Schöne hierbei ist, dass dies viele Kollegen auf einmal tun können und so parallel an derselben Doku arbeiten können. Am Ende des Tages Kollegin R. mit ihrer Arbeit hochzufrieden und möchten diese in das zentrale Repository laden. Bei SVN heißt das committen.

Sobald die Änderungen im Repository sind, kann jeder andere Kollegen updaten, sprich: seine lokale Arbeitskopie aktualisieren und hat Kollegin Rs Änderungen automatisch drin. Eine feine Sache, so ist jeder auf dem aktuellen Stand.

Aber oh weh – als Kollegin T versucht, ihre Arbeitskopie zu aktualisieren, um die Änderungen von Kollegin R in ihre Kopie zu übernehmen (dieser Vorgang des Zusammenführens heißt mergen), wird ihr angezeigt, dass es einen Konflikt gibt. Das heißt soviel wie, dass Kollegin R und Kollegin T an derselben Stelle eine Änderung vorgenommen haben und SVN natürlich nun nicht entscheiden kann, welche Änderung die bessere ist. Deswegen wird es Kollegin T auch angezeigt, damit sie diesen Konflikt irgendwie auflösen kann.

Ordnung in SVN

Im Prinzip könnte ich meine Ordnerstruktur direkt einchecken und damit arbeiten. In SVN gibt es jedoch auch noch ein paar Nützlichkeiten, was die Dateiorganisation anbelangt.

• Tags: Damit wird mir ermöglicht einen bestimmten Stand mit einem Stichwort, also einem Tag, zu versehen, um später die jeweiligen Versionsstände aller beteiligten Dateien, die beispielsweise zu einem bestimmten Release gehören, auf einen Schlag wiederzufinden. Ein Beispiel für einen Tag wäre also die Releasenummer der Software, die man dokumentiert.
• Branches: Nun kann es passieren, dass man schon längst wieder an der Doku für das nächste Release arbeitet, und es erreicht einen die Nachricht, dass es in der Version für das letzte Release einen happigen Fehler gab, der für die Kunden, die es nutzen, gefixt werden muss. Das ist der Punkt, wo man anfangen würde einen neuen Entwicklungszweig (branch) aufzumachen. Man arbeitet also an einer Stelle noch am Handbuch für das alte Release (im branch) und an der anderen für das neue (im sog. trunk, dem Hauptentwicklungszweig). Das Schöne ist auch, dass es die Möglichkeit gibt, diese zweige zusammenzuführen. Um beim genannten Beispiel zu bleiben: der Fix im alten Release könnte auch für das neue Release vonnöten sein. Hier könnte man dann wieder mergen.

DITA-Doku in SVN reloaded

Das heißt, die Ordnerstruktur mit SVN könnte also so aussehen: