Breadcrumbs in DITA-XHTML – Update

Ich habe das Breadcrumbs-Plugin ja bereits vorgestellt. Der damalige Bug bei der Verwendung von Reltables war sehr schnell behoben – superklasse!

Aber schon damals ist mir eine unschöne Sache aufgefallen: der Text für das Wurzelelement in der Breadcrumb ist hart kodiert. Das ist natürlich gerade bei der Internationalisierung der Hilfe eher so ein bisschen doof. Schließlich will ich ja nicht für jedes Generieren jeder Sprache immer wieder die Stylesheets anfassen. Daher hab ich eine Internationalisierung an dieser Stelle eingebaut, d.h. der Text für das Wurzelelement wird je nach Sprache der Map & Topics generiert.

Wer sich dafür interessiert, befolge bitte diese Schritte:
In der Datei dita.xsl.maplink.xsl aus dem Plugin wird dieser Schnipsel
<xsl:param name="indexLinkText" select="'Index'"/>>

zu diesem


<xsl:param name="indexLinkText">
<xsl:call-template name="getString">
<xsl:with-param name="stringName" select="'Start'"/>
</xsl:call-template>
</xsl:param>

In der de-de.xml im xsl-Verzeichnis des Toolkits muss natürlich der entsprechende String angelegt werden:
<str name="Start">Start

Dann muss man noch den obigen Schnipsel aus Zeile 9 in das xsl-Template (ab Zeile 14) verschieben, also so:

<xsl:template match="*" mode="link-to-other">
<xsl:param name="pathBackToMapDirectory"/>
<xsl:param name="indexLinkText">
<xsl:call-template name="getString">
<xsl:with-param name="stringName" select="'Start'"/>
</xsl:call-template>
</xsl:param>
<xsl:if test="$doAncestors='yes'"> ......

Wenn man die Parameterdefinition global belässt, wird immer nur en-us als Sprache erkannt, warum auch immer.

So, das war's auch schon. Und zu meinen Tricks, um mich beim Programmieren und Testen bei Laune zu halten, gehören motivierende Ausgabetexte für den Fall, dass es endlich klappt, und eher so die destruktiven für den anderen Fall 😉

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 🙂

Gelesen: DITA – Der neue Standard für technische Dokumentation

Bisher sind die Informationsquellen bzw. die Literatur zu DITA eher rar, im Endeffekt bleibt man beim User-Guide und der Yahoo-Group hängen und sammelt sich dort alles irgendwie zusammen.

Nun bin ich endlich dazu gekommen mir das erste deutschsprachige Buch rund um DITA zu bestellen und zu lesen: DITA – Der neue Standard für technische Dokumentation von Johannes Hentrich. Frau Closs Buch konzentriert sich ja mehr auf Topicorientierung als auf DITA, auch wenn das natürlich gut zusammenpasst.

Was steht zu DITA drin?

Es ist so ziemlich alles drin, was man über DITA wissen muss:

  • Welche Philosophie dahinter steht,
  • wie es funktioniert,
  • was das Open Toolkit ist,
  • wie man den Output, also die Stylesheets, verändert,
  • wie man mit DITA wiederverwendet und filtert,
  • welche Editoren es gibt,
  • warum ein CMS Sinn macht…

Sehr gut fand ich die Anwendungsbeispiele. Erst hier hab ich mal so richtig kapiert, was chunking eigentlich bedeutet (und das werde ich hier sicherlich mal noch in eigenen Worten wiedergeben). Ein bisschen überflüssig fand ich, dass sehr viele Dinge wiederholt wurden, z.B. was Topicorientierung bedeutet…

Unnötige Basics

So gut ich den Umfang zu DITA fand, so schlecht fand ich, dass das Buch gleichzeitig noch versucht einen Rundumschlag in Sachen „Technische Redaktion“ zu machen. Das macht das Buch ein bisschen unausgewogen in seiner Zielsetzung. Und mal ganz ehrlich – wenn man sich in DITA reinkniet und bereit ist Stylesheets u.ä. anzufassen, dann muss man hier nicht bei den Binsenweisheiten der TDOKU anfangen. Ja, ich weiß, dass Standardisierung wichtig ist und Wiederverwendung sowieso. Wer es nicht weiß, hat den falschen Beruf gewählt oder sollte erst einmal bei den echten Basics-Büchern anfangen.

Rechtschreibprüfung?

Was mein Redakteusenauge sehr genervt hat, waren die zahlreichen Tippfehler und auch Satzfehler in dem Buch. Mindestens alle drei Seiten war irgendetwas falsch geschrieben oder umgebrochen. Für das nächste Buch empfehle ich hier einen sorgfältigeren Lektor. Bei so einer kritischen Zielgruppe MUSS da alles stimmen.

Fazit

Für Leute, die sich in DITA reinknien wollen, ist das Buch auf jeden Fall das Richtige. Die unnötigen Kapitel kann man ja zum Glück einfach überspringen 😉 Ansonsten bekommt man alle Infos, insbesondere auch die zum Toolkit kompakt und gut dargestellt und erklärt. Dieser Teil hat mich persönlich sehr überzeugt.

Für Anfänger in der technischen Doku hingehen enpfehle ich das Buch eher nicht, da die Kapitel, die richtig in die DITA-Materie reingehen, hier meiner Meinung nach eher abschrecken / überfordern.

Zum Abschluss muss ich noch erwähnen, dass ich die Behauptung, dass gute Stichwortverzeichnisse bei Büchern kaufentscheidend sind, sehr witzig fand. Das trifft bei mir allerhöchstens auf Lexika und Telefonbücher zu 😉 Ansonsten ist in der Regel sicherlich das Inhaltsverzeichnis der ausschlaggebendere Punkt, nicht umsonst stellt amazon bei vielen Büchern das Inhaltsverzeichnis online zur Verfügung. Keine Frage Indizes sind ein wichtiges Navigationsmittel, aber meist bemerke ich die erst weit nach dem Kauf.Umso lustiger fand ich es aber mir auf diese Aussage hin mal den Index dieses Buchs anzuschauen und etwas darin zu suchen. Es sei nur soviel gesagt: Er sollte nicht eure Kaufentscheidung beeinflussen. Denn eigentlich lohnt sich das Buch 🙂

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 🙂

XHTML-Output anpassen

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 🙂