Die tekom-Jahrestagung 2012 ist überstanden und es war mal wieder sehr interessant und schön dabei zu sein.
Vorab gibt es hier erst einmal die Folien zu meinem Vortrag „Mit DITA um die Welt“. Der Rückblick folgt in den nächsten Tagen. Ich gehöre nicht zu den Schnell-Bloggern wie Kai oder Sarah, die ihre Eindrücke wirklich rasend schnell online hatten.
Und hier noch der Beweis, dass ich ihn tatsächlich gehalten habe 😉
(Special thanks to Axel)
Das DITA-Open Toolkit unterscheidet im XHTML-Output zwischen Links auf Concepts, References und Tasks. Konkret werden die Links wie hier angezeigt:
Mal abgesehen davon, dass die vom Open Toolkit mitgelieferten deutschen Standard-Überschriften „Zugehörige Konzepte/Tasks“ etwas wunderlich klingen, bin ich persönlich kein Freund dieser Aufteilung der Links.
Ich habe z.B. an der Hochschule gelernt, dass solche Topic-Beziehungen klassifiziert und standardisiert werden sollten. Zum Beispiel indem man festlegt, welche Topictypen einander verlinken dürfen und wie. Das finde ich auch absolut okay und notwendig, denn so kann man verhindern, dass unsinnige Link-Urwälder entstehen in denen jedes Topic jedes andere Topic verlinkt, was dann am Ende nicht mehr sehr hilfreich für den Nutzer ist.
Aber: ich bin mir nicht sicher, ob diese Klassifizierung dem Nutzer an dieser Stelle unbedingt so vermittelt werden muss. Hat der Nutzer tatsächlich etwas davon, wenn ich ihm sage: hier kannst du verwandte Anleitungen finden und hier verwandte Erklärungen? Manchmal weiß der Nutzer doch selbst gar nicht so genau was er sucht und ist so eine Klassifizierung nicht vielleicht einfach nur ein Stolperstein?
In meinen Augen ringt so eine Aufteilung dem Nutzer noch einmal eine Entscheidung zuviel ab, die er auf der Suche nach der passenden Information treffen muss. Er muss sich dann nochmal fragen: „Ja, was such ich denn eigentlich?“ und ehrlich gesagt ist man nicht in der Stimmung über so etwas nachzudenken, wenn man Hilfe sucht. Daher plädiere ich dafür verwandte Links unter einer Überschrift zusammenzufassen. Mir geht diese Aufteilung auf Nutzerseite einen Schritt zu weit und sie hat so ein bisschen was von „Ich mach es so. Weil ich es kann.“
Wie seht ihr das? Was macht ihr mit Links auf verwandte Themen und warum?
Das DITA-Open-Toolkit bringt schon ziemlich viele Sprachen mit sich, aber irgendwo findet sich doch immer eine, die doch noch nicht abgedeckt ist. Das Hinzufügen neuer Sprachen ist glücklicherweise kein Hexenwerk. Allerdings gilt letztere Aussage nur für Sprachen mit der Schreibrichtung „links nach rechts“ – die andere Richtung hab ich noch nie getestet und weiß nicht, ob es da noch andere Dinge zu beachten gilt.
Das Sprachkürzel herausfinden
Im Attribut xml:lang jedes Topics muss die Sprache angegeben werden. Es gibt verschiedene Übersichten im Netz über diese so genannten „Locale IDs“ , z.B. hier. Nehmen wir mal an, ich möchte kolumbianisches Spanisch einbinden. So lautet das Kürzel also: es-co.
Sprache in strings.xml hinterlegen
xsl/common in deinem DITA-OT.strings.xml.
Neue Sprachdatei anlegen
xsl/commonund füge sie unter dem Namen es-co.xml in dasselbe Verzeichnis ein.Fertig!
Das war es tatsächlich schon. Ab sofort kannst du in den Topics und Maps das neue Sprachkürzel verwenden und die automatischen Strings wie z.B. „Hinweis“ oder „Achtung“ werden entsprechend lokalisiert 🙂
Der Dating DITA-Vortrag kommt mir gerade wieder in den Sinn, wo ich mich Metadaten beschäftige. Und da stehen mir wirklich die Haare zu Berge – das ist das erste Mal, dass ich DITA wirklich, wirklich unpraktisch finde und noch keine gute Lösung habe, wie ich da in Zukunft verfahren soll.
Wie man komplette Topics nicht rausfiltert
Nehmen wir mal an, ich generiere aus einer Map einen User-Guide und einen Admin-Guide. Viele Inhalte überschneiden sich, aber einige sind exklusiv nur für eine der Zielgruppen gedacht.
Bisher dachte ich mir das so: Wenn ich von einem kompletten Topic weiß, dass es nur audience=“user“ ist, dann setz ich das Attribut auf das Root-Element, also so:
<task id="123" product="wundertuete2" audience="user">...
Dann wird doch dieses Topic, auf diese Weise attributiert, nun beim Generieren des Admin-Guides bestimmt nirgends verlinkt bzw. gar nicht erst generiert.
Weit gefehlt. Das Topic wird generiert und zwar leer (und damit nicht valide). Alle Verlinkungen, sprich: alle Topicrefs, sind auch im Output existent, führen aber natürlich ins Leere.
Wie man komplette Topics wirklich rausfiltert
Um zu verhindern, dass etwas überall verlinkt wird, muss man das Attribut auf jeden Topicref setzen!
<topicref id="123" product="wundertuete2" >
<
Und zwar auf wirklich jeden, auch die in den Relationship tables. Und das in allen Maps in denen das Topics vorkommt. Wenn ich da an zentrale, so gut wie immer gültige Attribute wie audience oder product denke, wird mir übel. Wie soll man das denn anständig pflegen oder gar mal aktualisieren? So müsste jeder Redakteur für jedes Topic erneut prüfen, welche Gültigkeit es hat und es auch wieder in der Map hinterlegen. Und darauf hab ich eigentlich überhaupt keine Lust.
(Im Übrigen gilt das Prinzip nicht nur für Topicrefs, sondern auch für den Einsatz anderer interner Verlinkungsarten wie xref oder related-links)
Zudem ist es sehr inkonsistent, dass es hier plötzlich ein eigenes Element audience gibt, zusätzlich zum gleichnamigen Attribut. Um die Verwirrung zu komplettieren, kann man beides gleichzeitig auf einen einzelnen Topicref beziehen.
<topicref id="123" product="wundertuete2" audience="user">
<topicmeta>
Eine passende Diskussion auf der Yahoo-Group hab ich schon gefunden, aber eben leider noch keine Lösung. Und sowas muss ich kurz vor dem Wochenende rausfinden 🙁
Heute ein kleiner Wissensschnipsel zu Dateiendungen in DITA. Prinzipiell ist es inzwischen erlaubt, sowohl Dateien mit XML-Endung als auch welche mit DITA-Endung in eine Map zu integrieren. Ich persönlich finde ja so einen Misch-masch nicht gut, und als ich es mal getestet habe, hat es auch nicht gut funktioniert.
Kommen wir aber zu einem Problem, das seine Ursache in diesem Misch-Masch hat, und das in den meisten Fällen gar kein Problem ist, außer man schafft es mal wieder einen Sonderfall zu erwischen. So wie ich 😉
Ich musste gerade bei einer Transformation einem Topic die Information mitgeben, welchen Parent es hat – und zwar musste es die ID des Parents sein.
Da kam mir sehr gelegen, dass in unserem Redaktionssystem der Dateiname auch als Topic-ID fungiert .
[xml]<task id="d262.dita">…</task>[/xml]
Also geb ich hier einfach das href-Attribut des Parents aus, das ja den Dateinamen beinhaltet. Sehr einfach, juhu!
[xml]<xsl:value-of select="../@href"/>[/xml]
Aber Moment im Endergebnis der Transformation finde ich plötzlich das hier
[xml]
<topic id="t_Duda.dita">
<title>Duda</title>
<topic parentid="t_Duda.xml" id="t_Dida.dita">
[/xml]
Die Parent-ID stimmt im Prinzip, bloß ist da plötzlich XML als Dateiendung angegeben! Was soll das denn jetzt?
Ich habe eine Weile gesucht, blieb aber ratlos. Ein Artikel zur Verwendungvon Dateien mit XML-oder DITA-Endung hat mich dann auf die Lösung gebracht. Beim Generieren der temporären Dateien aus denen das Toolkit letzten Endes die Ausgabe baut, kann man sich auch „aussuchen“ welche Dateiendung diese temporären Dateien haben sollen.
Standardmäßig werden sie in XML generiert, aber das kann man in seinen Build-Dateien auch ändern.. Also habe ich in meine Build-Datei flugs folgenden Parameter eingebaut:
[xml]<param name="dita.extname" value="dita"/>[/xml]
Und schon hat es gepasst!
[xml]
<topic " id="t_Duda.dita">
<title>Duda</title>
<topic parentid="t_Duda.dita" id="t_Dida.dita">
[/xml]
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 😉
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:
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 🙂
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:
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 🙂
Ich habe nun damit angefangen Anpassungen vorzunehmen.
Im Groben sind dazu folgende Schritte notwendig:
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
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.
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 🙂
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 🙂