Die Redakteuse

Schlagwort: how-to

  • Breadcrumbs in DITA-XHTML

    Der Name Breadcrumb-Navigation wurde in Anlehnung an das Märchen Hänsel und Gretel der Brüder Grimm gebildet, in dem die in den Wald geführten Kinder Brotkrumen (englisch breadcrumbs, plurale tantum) auf den Weg streuen, um den Weg zurück zu finden (PediaWiki)

    Mir geht es speziell um die „Location-Breadcrumbs“, d.h. ich möchte, dass in meiner HTML-Hilfe sichtbar ist, wo in der Hierarchie sich der Nutzer gerade befindet.

    Ein sehr klassisches Instrument in der Nutzerführung, das aber lustigerweise in dem Standard-XHTML-Output gar nicht drin ist.

    Nachdem ich etwas recherchiert habe, bin ich recht schnell auf ein relativ frisches Plugin gestoßen, das genau das macht: Ancestors

    So sieht eine Topic-Seite in HTML dann auch aus, wenn man sie generiert:

    Installation

    Die Installation ist denkbar einfach:

    1. Herunterladen.
    2. Das Verzeichnis qwcode.ancestors in das plugins-Verzeichnis im DITA-OT kopieren.
    3. Im DITA-OT-Verzeichnis eine Shell öffnen und ant -f integrator.xml eintippen.
      –> In der Datei dita2xhtml.xsl sollte das Stylesheet des Plugins nun referenziert werden.
    4. Im Verzeichnis qwcode.ancestors eine Shell öffnen und ant buildDemo eintippen.
      –> Hier sollten nun im Unterverzeichnis demo/xhtml die XHTML-Dateien generiert werden.

    Das ganze hat bei mir echt gut geklappt und daher spreche ich eine eingeschränkte Empfehlung aus. Die Einschränkung folgt auch sofort.

    Bug bei Verwendung von reltables

    Aktuell werden leider bei allen Topics, die in Reltables referenziert werden, die Breadcrumbs falsch dargestellt, so wie in diesem Beispiel, in dem die Startseite „Index“ zweimal verlinkt wird. Das zu fixen ist sicherlich kein Hexenwerk, aber ich habe gerade keine Zeit…  Wenn das aber gefixt ist, empfehle ich absolut uneingeschränkt 🙂

  • DITA und XMetal

    Und jetzt erst finde ich diese Präsentation von Simon Bate (Scriptorium)! Meine Güte, da hätte ich mir einiges an nerviger Recherche sparen können.

    Aber ich will mein Wissen natürlich brav weitergeben: also holt euch Popcorn, was zu schreiben und stellt das Radio aus. Hier wird es wirklich interessant und praxisbezogen 🙂

    XMetaL DITA Workshop

    View more presentations from Scriptorium.

    Hierbei muss ich erwähnen, dass ich Slideshare einfach großartig finde. Im deutschen Raum scheint es noch gar nicht sehr verbreitet zu sein. Vielleicht sollte man das auch mal den Leuten der tekom zeigen. Es wäre ja viel cooler, die Tagungspräsentationen hier zu posten, als irgendwo in den Irrungen&Wirrungen der tekom-Webseite (die sich nicht gerade durch einen großen information scent hervortut). Und ich glaub auch fast, dass man hier auch mehr Hits erhalten würde.

  • DITA-Output filtern mit XMetal

    Wiederverwendung und Varianten
    Das Filtern wird in Zeiten der Wiederverwendung früher oder später notwendig. Man hat beispielsweise ein Produkt, dass es in einer Light-Version und einer Vollversion gibt. Natürlich werden sich hier die Hilfetexte zum größten Teil überschneiden – bis auf die kleinen Ausnahmen, wo dann in der Vollversion hier noch ein Schritt weniger ist und dort eine Option mehr verfügbar. Man hat also eine Wiederverwendungsquote von 90%, aber was tun? Die Hilfetopics nun zweifach vorhalten? Ne, da sträuben sich jedem guten Redakteur die Haare. Redundanz, nein danke!

    Nun, wie wär’s, wenn man einfach alle Varianten in eine Datei schreibt und die Teile, die nur für ein Produkt gelten mit einem Attribut versieht? Und dann beim Generieren einen Filter definiert, der nur Teile generiert, die einen bestimmten Attributwert enthalten? Klingt cool – isses auch!

    Attribute in DITA
    Es gibt für DITA schon einige fest definierte Attribute, die man an fast jeden Tag vergeben kann. Es sind gängigen Attribute nach denen man in der Doku filtert und für die man frei Werte definieren kann:

    • product
    • audience
    • platform
    • outputclass (erst ab DITA OT 1.4 unterstützt)

    Zu guter Letzt gibt es das otherprops-Attribut, das so ziemlich alles enthalten kann. Eine Art Auffanglager für den Rest sozusagen.

    DITA-Attributvergabe im XMetal

    Wir nehmen uns nun ein Beispiel, in dem ein bestimmter Handlungsschritt nur in der Print-Hilfe auftaucht und in der Online-Hilfe nicht, weil die Online-Hilfe kontextbasiert ist und ein Zwischenschritt wegfällt, der aber in der Print-Version nötig ist.

    Eigentlich sollte man dazu ab DITA 1.4 das Attribut outputclass verwenden, da ich aber noch auf DITA 1.3 arbeite, werde ich also das otherprops-Attribut verwenden. Ich markiere den <step> und  schreibe im Attribute Inspector einfach den Wert hinein nach dem ich filtern möchte.

    Der Nachteil hierbei ist, dass je nach Attributwert einem anderen Redakteur nicht unbedingt von Namen her sofort klar ist, nach was hier gefiltert wird. Wenn ich z.B. handbook als Wert eingebe, kann das einerseits bedeuten, dass ich für den PDF-Output etwas filtern möchte (es also eine technische Bedeutung hat) oder aber für den Dokumenttyp „Handbuch“ (was dann eher inhaltliche Bedeutung hat).

    Filterregeln in XMetal anlegen

    Hierzu muss man folgende Datei öffnen: c:\Programme\XMetaL 5\Author\Conditional Text\configs\ct_config.xml

    Hier kann man nun seine Attributwerte definieren und festlegen, wie diese in der Filterauswahl angezeigt werden. Ich habe hier den Attributkomplex zu otherprops bearbeitet. Für jeden Attributwert definiert man einen <value>-Tag, in name steht der Attributwert und in title steht der Anzeigename in der Filterauswahl.

    ´[....]

    Filterregeln auswählen

    1. Auf File > Generate Output from DITA map klicken.
    2. Im Dialog auf Show/Hide Conditional Text klicken.
    3. Hier kann man nun auswählen, welche Filterkriterien für den aktuellen Output gelten sollen.
      Ich will nun beispielsweise eine Online-Hilfe generieren, d.h. der <step>, der nur für Handbücher gilt, soll nicht generiert werden. Also klicke ich das Filterkriterium Onlinehelp an. Es wird alles generiert, was keinen Wert für dieses Attribut hat oder eben genau diesen Wert, d.h. der <step> mit dem Attributwert Handbook wird hier nicht generiert werden.

    Ergebnis
    Am Anfang steht also dieser Code:

    Öffnen Sie das Programm.

    Klicken Sie auf

    DateiNeu

    Editieren Sie die Datei.

    Und am Ende dieser Text:

    1. Klicken Sie auf Datei > Neu.
    2. Editieren Sie die Datei.

  • XHTML-Output anpassen #2 – Wie mache ich einen Override?

    Ich habe nun damit angefangen Anpassungen vorzunehmen.

    Im Groben sind dazu folgende Schritte notwendig:

    1. Plugin-Verzeichnis und Dateien anlegen.
    2. Plugin integrieren.
    3. XSL anpassen.

    Plugin-Verzeichnis und Dateien anlegen

    Dazu habe ich unter DITA_OT/demo ein Verzeichnis meinxhtml für meine Overrides angelegt, d.h. hier liegen meine Anpassungen für den XHTML-Output. Für DITA ist das einfach ein Plugin.

    In diesem Verzeichnis befindet sich ein Ordner mit meinen XSL-Dateien und die plugin.xml. In dieser Datei muss man dem DITA-OT sein Plugin quasi bekannt machen. Das sieht dann so aus:

    Plugin integrieren

    1. Hierzu öffnet man sich eine Konsole im DITA-OT-Verzeichnis und führt folgenden Befehl aus: ant -f integrator.xml
      Ob das wirklich geklappt hat, kann man in der Datei xsl/dita.2xhtml überprüfen. Dort sollte die XSL-Datei nun über ein <xsl:import> referenziert werden.

    XSL anpassen

    Jetzt kommt der wirklich spannende Teil. Wie schon erwähnt, wird das meiste über die Datei dita2htmlImpl.xsl gemacht. Wenn ich also nun etwas Bestimmtes modifizieren will, z.B. dass nach dem Titel einer Note kein Doppelpunkt kommt, gehe ich wie folgt vor.

    1. Ich schaue über Firebug in den Quelltext des Outputs, um zu sehen, ob der Bereich irgendwie besonders ausgezeichnet ist. Im Falle der Note sehe ich, dass der Note-Title in einem span-Tag steht und mit der CSS-Klasse notetitle ausgestattet ist.
    2. Über diese Hinweise finde ich dann in der XSL-Datei das entsprechende XSL-Template für diesen Bereich:
    3. Ich kopiere nun das komplette Template in meine mein_xhtml.xsl.
    4. Um den Doppelpunkt zu entfernen, lösche ich die entsprechenden Anweisungen. In diesem Beispiel also: 

    5. Diese Änderung speichern.
    6. Output generieren.
      Und nun sollte der Doppelpunkt verschwunden sein. Leider muss man den Doppelpunkt für alle Note-Typen entfernen, die es gibt, also für Tipps, Warnungen etc.

    Hiermit lässt sich schon mal sehr viel machen. An die Grenzen der Overrides kommt man beim OT 1.3, wenn es um die Anpassung des Inhaltsverzeichnisses geht. Hier funktionieren Overrides nämlich leider, leider nicht. Doch dazu ein anderes Mal mehr 🙂

  • DITA-Texte anpassen

    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?