Ditalog
msgbartop
DITA für Redakteure – von Single Source Publishing bis Self-Publishing
msgbarbottom

02 Apr 14 Bootstrapping Your DITA

DITA-OT Dokumentation mit bootstrap.css erstellt

DITA-OT-Dokumentation mit Twitter Bootstrap auf github pages veröffentlicht.

Neulich stieß ich auf Carlos Evias Blogpost Bootstrapping Your DITA for Sweet Responsive HTML5 Help. Sein Ziel war es, herauszubekommen, wie der derzeitige Chefarchitekt des DITA-Open Toolkits, Jarno Elovirta es geschafft hat, seine DITA-Quelldateien in Bootstrap-HTML-Output zu gießen. Leider blieb es mehr bei einer lustigen Anekdote. Es gab keine nachvollziehbare Anleitung. Trotzdem gab Carlos mir viel Hilfestellung per E-Mail. Mein Weg des Bootstrappings habe ich im Ditalog veröffentlicht. Das 4. Petersilienbuch Baukasten oder Puzzle? diente mir als Beispielprojekt.

DITA und Bootstrap auf github pages

Beispielprojekt auf petersell.com

Dieser Artikel ist im kostenlosen eBook Ditalog als EPUB und PDF-Datei verfügbar.

14 Feb 14 Quelldateien auf github.com bereitstellen

Git Versionsverwaltung für DITA-DateienDa meine eBooks unter einer Creative Commons Lizenz veröffentlicht werden, spricht alles dafür, die DITA-Quelldateien ebenso zu veröffentlichen. In meinem Fall auf github.com. Nebenbei lerne ich also Versionskontrolle.

Die Lernkurve zur Verwendung von git ist für Anfänger und Nichtprogrammierer recht hoch. Darum habe ich meine Erfahrungen in Sachen github.com in eine kurze Anleitung gegossen.

Sämtliche Petersilienbücher sind als DITA-xml-Dateien zu finden unter https://github.com/petersell

Dieser Artikel ist im kostenlosen eBook Ditalog als EPUB und PDF-Datei verfügbar.

05 Jul 13 Variablen ausserhalb des Projektordners

Variablen für sämtliche Projekte können mithilfe zweier Ant-Befehle weiterhin ausserhalb des Projektverzeichnisses abgelegt werden.

Gleiche Variablen in allen Projekten

Einige Angaben und Bilder werden in sämtlichen Projekten immer in gleicher Weise genutzt. Sie werden an zentraler Stelle gepflegt und als Variablen in die Topics eingefügt. Wenn sich eine Variable ändern soll, soll das in allen Projekten geschehen

Mithilfe von DITA-keyref Variablen definieriern

Grün umrahmte Adressen sollen in sämtliche Projekte eingefügt werden.

So ist die E-Mailadresse und die Internetadresse in sämtlichen Petersilienbüchern gleich. Gleichwohl möchte ich nicht auf die Möglichkeit verzichten, sie schnell auf einem Schlag ändern zu können. Speziell die E-Mail-Adresse möchte ich bei zu hohem Spamaufkommen ändern können.

Variablen erstellen im gemeinsamen Verzeichnis

Es liegt in innerhalb meines Petersilienbuch-Projektes folgende Ordnerstruktur vor:

includes
petersilienbuch-1
petersilienbuch-2

Im Ordner includes sind sämtliche Gemeinsamkeiten der Petersilienbücher enthalten. So auch eine keyref.ditamap mit den Angaben für E-Mail und Internetadresse – eben der globalen Variablen. Hier das Beispiel für die oben im Bild grün eingerahmte E-Mailadresse.

<map>
<keydef keys="petersell-mail-allgemein">
<topicmeta><keywords><keyword>Emailadresse@beispieldomain.de</keyword></keywords>
</topicmeta>
</keydef>
</map>

Variablen-Maps im Projektverzeichnis

In jedem Ordner für ein Petersilienbuch befindet sich eine keyref-Ditamap mit sämtlichen lokalen Variablen wie z.B. Download-URL oder Erscheinungsdatum. Und natürlich eine Haupt-Ditamap für jedes Petersilienbuch. Darin befinden sich zuoberst die Links zur globalen, danach die der lokalen keyref-ditamap-Datei.

<!-- Globale Variablen -->
<mapref href="../includes/maps/keyref.ditamap"/>
<!-- Lokale Variablen -->
<mapref href="maps/keyref-petersell-1.ditamap"/>

Topic mit eingefügter Variable

Die im Bild oben dargestellte Seite ist die Impressums-Seite eines jeden Petersilienbuchs. Um den Platzhalter für die E-Mailadress-Variable zu füllen, steht in der Concept-Datei für das Impressum folgende Notation:

<p><keyword keyref="petersell-mail-allgemein"/></p>

Ant-Befehle für die build-Datei

Bis zum Einsatz des DITA-OTs 1.5.3 funktionierte die Auslagerung der globalen Variablen ausserhalb der Projektordner fehlerfrei. Mit Einsatz des DITA-OTs 1.6.3 war dies nicht mehr möglich. Die globale, ausserhalb des Buchprojekts liegende keyref.ditamap wurde nicht verarbeitet.

[keyref] [DOTJ047I][INFO] Unable to find key definition for keyref=”petersell-mail-allgemein”, href may be used as fallback if it exists.

Bis ich bei Eliot Kimbers DITA for Practitioners [1] fündig wurde. Es fehlten 2 Zeilen in meiner build-Datei für das jeweilige Target (EPUB und PDF):

<property name= "generate.copy.outer" value="2"/>
<property name= "onlytopic.in.map" value="true"/>

Links zur Seite

[1] Eliot Kimber, DITA for Practitioners Vol. 1, zum Link

Dieser Artikel ist im kostenlosen eBook Ditalog als EPUB und PDF-Datei verfügbar.

07 Mrz 13 Every Page Is Page One

Behandeln Sie jede Seite einer Onlinehilfe oder eines eBooks wie eine Einstiegsseite: bieten Sie Orientierung für die nächsten Schritte und Vertiefung in weitere Themen in Form von Links an.

Dieser Artikel verdankt sein Entstehen dem glücklichen Eintreten zweier Ereignisse:

  1. Ich hatte über die Metadaten den Dateinamen eines Artikels im sichtbaren Text ausgeben können. Beschrieben ist die Vorgehensweise im Artikel Metadaten im Text – Name des Topics, im eBook enthalten.
    Datei- bzw. Seitenname im Output ausgeben

    Dateiname metadata-output_con sichtbar oben rechts

  2. Mark Baker veröffentlicht seinen Blogpost A New Approach to Organizing Help. Er bloggt unter der selbsterklärenden Domain Everypageispageone.com mit dem Motto Readers can enter anywhere. Is your content ready to receive them?

Jede Seite hat ein Thema und viele Aspekte – verlinken Sie!

Mark Bakers Blogname Every Page Is Page One ist programmatisch. Die Frage, ob ich eine komplexe Sache in eine große Online-Hilfe mit einem großen Inhaltsverzeichnis bündele oder die vielen Themen in mehrere Online-Hilfen splitte und somit ein aussagekräftigeres Inhaltsverzeichnis erhalte, beschäftigt viele Technische Redakteure. Doch das ist gar nicht nötig, meint Baker.

Every piece of content is rich in subject affinities. That is, the people, places, objects, actions, and ideas mentioned in the piece are connected to those people, places, objects, actions, and ideas, and thus have a connection (an “affinity”) to content that describes those people, places, objects, actions, and ideas.

Yet it is those affinities that actually define the place of a topic in its broader subject area. A traditional book index is an ordered list of the subject affinities in the book. A hypertext link in a Web page is the expression of an affinity between the content in which it occurs and content it links to. Subject affinities anchor a piece of content in time, culture and the reader’s experience.

When the user has landed in your help by way of a Google search, in search of information on a particular problem they are trying to solve, what kinds of additional information are they likely to need if the current topic does not entirely satisfy their needs? It is not information from other general categories of the help system, which is what the TOC provides. It is information related to the subject affinities of the current topic. [1]

In den Zeiten des Standards DITA 1.1 hieß es oftmals: Setzen Sie innerhalb des Textes keine Links zu anderen Topics! Dies lenkt den Leser ab und bringt Sie in Teufels Küche, so bald eine Topic-Datei mal verschoben oder gelöscht wird. Doch nun haben wir im Standard DITA 1.2 die Technologie des relatvien Verlinkens via keys und keyref[2]. Ein Link innerhalb des Textes ist nun kein Teufelszeug mehr. Ändert sich der Speicherort einer Datei, braucht dieser nur noch an einer Stelle geändert werden. Die Hyperlinks, die sich mit keyref auf diese Datei beziehen, aktualisieren die URL ganz von allein.

Dateiname gleich keys

Nun habe ich also den Mut, aus jeder Seite eine EPPO-Seite zu machen (Sie werden die Abk. dechiffrieren). D.h. ich werde nicht scheuen, zu anderen Seiten der Onlinehilfe oder des eBooks auch innerhalb des Textes zu verlinken. So können Sie vorgehen:

1. keys vergeben

Geben Sie in der ditamap in jedem topicref auch einen Begriff für keys ein.

<topicref href="../onlinehilfe/metadata-mailto_con.xml"
keys="metadata-mailto_con" scope="local" toc="yes" type="concept"
xml:lang="de-de"/>

Achten Sie darauf, dass Sie für keys einfach den Dateinamen eintragen. Hier im Beispiel metadata-mailto_con. Die Dateierweiterung xml ist nicht vonnöten.

2. Mit keyref auf keys referenzieren

Sie finden in einer anderen Datei ein Schlüsselwort (z.B. Feedback), zu welchem Details vorliegen und Sie verlinken könnten? Dann machen Sie das mithilfe der Elemente keyword oder xref und dem dazugehörigen Attributs keyref.

<keyword keyref="metadata-mailto_con">Feedback</keyword>

Während keyword standardmäßig nicht im PDF-Output ausgegeben wird, können Sie bei xref sicher sein, dass der Link im Online- als auch PDF-Output funktioniert.

<xref keyref="metadata-mailto_con">Feedback</xref>

Sie bearbeiten also die Quelldatei in Ihrem Editor und können parallel im vorher generierten Output schauen, zu welchen Seiten sie verlinken möchten. Der Seitenname wird ja jetzt oben rechts ausgegeben. Kopieren Sie ihn einfach und fügen Sie ihn bei keyref als Wert ein. Im obigen Beispielbild ist der Dateiname metadata-mailto_con auch der Wert, den Sie in der ditamap-Datei auch bei keys hinterlegt haben.

Der Dateiname wird also als Identifikation für die E-Mail-Rückmeldung des Nutzers benutzt, aber auch als schnelle Linkmöglichkeit für den keys-keyref-Mechanismus.

Links zum Artikel

[1] A New Approach to Organizing Help, Mark Baker, 2013, zum Link

[2] DITA 1.2 feature article: Keyref overview, Sowmya Kannan, 2009, zum Link

Dieser Artikel ist im kostenlosen eBook Ditalog als EPUB und PDF-Datei verfügbar.

21 Feb 13 Metadaten im Text ausgeben

So geben Sie z.B. das Datum der letzten Änderung unterhalb des Seitentitels aus.

Dieser Artikel ist im kostenlosen eBook Ditalog als EPUB und PDF-Datei verfügbar.

Seit Jahren war ich auf der Suche nach einem Weg, die Metadaten, speziell das Erstellungs- und Aktualisierungsdatum eines Topics, im Text auszugeben. Da ich keine Lösung dafür hatte, habe ich das Aktualisierungsdatum immer im abstract hart kodiert. Bis ich im XMetal-Forum auf ein Skript stieß, das die beiden Datumsangaben im PDF-Output mit ausgibt. Dies habe ich selbst noch nicht ausprobiert. Da ich die Datumsangaben für den XHTML-Output benötige, habe ich das Skript für meine Online-Publikationen folgendermaßen angepaßt.

So soll es aussehen

Aktualisierungsdatum im Text ausgeben

Aktualisierungsdatum in der CHM-Hilfe

In den Formaten CHM, XHTML und EPUB soll oben rechts immer das Datum der Erstellung und der letzten Änderung in grauer Schrift kursiv ausgegeben werden. Und zwar rechtsbündig unterhalb des Titels und vor der Kurzbeschreibung shortdesc.

Metaangaben im Topic

Vorraussetzung ist, dass in jedem Topic, egal ob Task oder Concept etc, folgende Metadaten innerhalb des Tags prolog gefüllt sind.

<critdates>
  <created date="08.06.2012"/>
  <revised modified="01.07.2012"/>
</critdates>

Hat das Topic noch kein Änderungsdatum, lassen Sie den Tag für revised weg.

gen-user-header-Template anpassen

Suchen Sie innerhalb Ihres DITA-Open Toolkits im Ordner xsl/xslhtml nach der Datei dita2htmlImpl.xsl. Innerhalb dieser Datei muss das Template gen-user-header angepasst werden. Es ist das zweite Template im Bereich, der extra für Ihre Modifikationen für den Header, Footer etc angelegt wurde.

<!-- ========== STUBS FOR USER PROVIDED OVERRIDE EXTENSIONS ========== -->

Im vorhandenen Template gen-user-header fügen Sie, wie unterhalb des Kommentars folgende Zeile ist neu aufgeführt, eine neue Zeile ein.

<xsl:template name="gen-user-header">
  <xsl:apply-templates select="." mode="gen-user-header"/>
</xsl:template>
<xsl:template match="/|node()|@*" mode="gen-user-header">
  <!-- to customize: copy this to your override transform, add the content you want. -->
  <!-- it will be placed in the running heading section of the XHTML. -->
  <!-- folgende Zeile ist neu! -->
  <xsl:apply-templates select="*[contains(@class, ' topic/prolog ')]" 
  mode="gen-user-header"/>
</xsl:template>

Unterhalb dieses angepaßten Templates gen-user-header fügen Sie ein zweites Template hinzu.

<xsl:template match="*[contains(@class, ' topic/prolog ')]">
  <p align="right">
    <xsl:if test="*[contains(@class,' topic/critdates ')]/
    *[contains(@class,' topic/created ')]/@date">
    <span>Erstellt am <xsl:value-of select="*[contains(@class,' topic/critdates ')]/
    *[contains(@class,' topic/created ')]/@date"/>.   </span></xsl:if>
    <xsl:if test="*[contains(@class,' topic/critdates ')]/
    *[contains(@class,' topic/revised ')]/@modified">
    <xsl:for-each select="child::*[contains(@class,' topic/critdates ')]/
    *[contains(@class,' topic/revised ')]">
    <span>Letzte Änderung: <xsl:value-of select="@modified"/></span>
    </xsl:for-each>
    </xsl:if>
   </p>
</xsl:template>

Formatierung in der CSS-Datei

Der Absatzp hat eine class="header-metadata" erhalten. Diese Klasse müssen Sie noch Ihrer CSS-Datei hinzufügen.

.header-metadata
{
  text-align: right;
  font-style: italic;
  color: #C2C2C2;
  margin-right:10px;
}

Plugin

Da ich die Metadaten nur für Onlinehilfen und eBooks benöte, die des Öfteren aktualisiert werden, habe ich das Template in ein Plugin ausgelagert.

Links

Skript für Metadaten im Text für PDF-Dateien im XMetal-Forum

Dieser Artikel ist im kostenlosen eBook Ditalog als EPUB und PDF-Datei verfügbar.

18 Feb 13 Bildunterschrift im XHTML-Output

Bildunterschrift unterhalbWann immer ich auf ein aktuelleres DITA Open Toolkit umsteige, werde ich schmerzlich daran erinnert, welche Modifizierungen ich noch nicht als Plugin ausgelagert habe. Kaum war ich auf das DITA OT 1.6.3 umgestiegen, standen meine Bildunterschriften im Online-Output wieder oberhalb der Bilder. Ich habe das Template für figcap nun in ein Plugin ausgelagert. Die Beschreibung findet sich im Ditalog im Kapitel Ideen für Online-Hilfen. Es betrifft aber natürlich auch die Generierung von EPUB-Büchern.

Dieser Artikel ist im kostenlosen eBook Ditalog als EPUB und PDF-Datei verfügbar.

17 Jan 12 FAQ-Plugin in das DITA-OT einbinden

Zum zweiten Mal habe ich den Versuch unternommen, das FAQ-Plugin, das standardmäßig im DITA-OT mit ausgeliefert wird, in mein Toolkit einzubinden. Mit Erfolg. In der DITA-Users-Group gab Eliot Kimber den Hinweis, nach welcher Anleitung man dabei vorgehen kann. Da sich bei mir jedoch einige Abweichungen ergaben, hier in folgender Anleitung meine Erfahrungen beim Einbinden der FAQ-DTD.

Weiterlesen als PDF

Lesen Sie den ganzen Artikel als PDF-Datei weiter »

Angaben zum Artikel

Artikel als PDF anzeigen
Aufrufe bzw. Downloads: 863
Aktualisiert am: 27.01.2012
Autor: Andreas Petersell
In Gesamtausgabe: In Gesamtausgabe enthalten
Dieser Artikel ist im kostenlosen eBook Ditalog als EPUB und PDF-Datei verfügbar.

24 Nov 11 Der Romantische Nebel des Buchmarkts (RNB)

Im Oktober 2011 schrieb Sascha Lobo seine Allgemeinen Feststellungen zur Buchsituation. Nicht nur der Titel, auch der erste Absatz der Feststellungen gleichen einem Manifest:

0. Ich möchte in einer Welt leben, in der kluge Leute für das Nachdenken bezahlt werden, und dazu sind Bücher ziemlich gut geeignet. Das ist übrigens auch mein Argument für ein starkes Urheberrecht (mit digitalen Anpassungen, allerdings).

Leider verhält es sich bei mir nicht ganz so romantisch – obwohl ich mein Geld auch durch Nachdenken verdiene. Ich habe als Technischer Redakteur meine Urheberrechte am ersten Arbeitstag meinem Chef überschrieben. Er bezahlt mich nicht fürstlich, aber regelmäßig. Dafür gibt er täglich das Thema vor. Nun werde ich mich mit allzu harscher Kritik gegenüber meinem Chef zurückhalten. Solange wohl, wie dessen Geschäftsmodell mich und meine Familie ernährt.

Der Buchmarkt wird so lange nicht mit einem neuen Geschäftsmodell aufwarten, wie er genug Menschen ernährt. Natürlich wird es immer einen Buchmarkt geben. Genauso wie es noch Druckereien mit Druckern aus Fleisch und Blut gibt, obwohl ja jeder einen Drucker auf dem Schreibtisch zu stehen hat. Wer schon mal versucht hat, eine ePub-Datei mit einem Schleifenband zu versehen, wird sich das gänzliche Verschwinden des Buchmarkts sowieso nicht wünschen.

Gestern hielt ich im Supermarkt Lobos Wortschatz-Taschenbuch in der Hand. Ein Meisterwerk der Taschenbuchkunst. Sowohl der Inhalt als auch das Design waren genial. Und trotzdem hätte ich es nicht für einen Euro gekauft. Es will etwas von meinem Zeitkontingent beanspruchen – mit unterhaltsamen Zeittotschlagen! Aber was ist schon das Lesen von unterhaltsamen Zeittotschlagtexten gegen das Schreiben eigener Texte? Gegen das Aktivwerden, das Kreieren, die Kommunikation? Es beschlich mich ein unbeschreibares Gefühl der Trauer.

Lobos Wortschaftzfähigkeit ist gewaltig. So konstatiert er in den Feststellungen zur Buchsituation, nirgends gibt es alle Bücher wegen DRM, dem Senfgas des Internet. Ich war entzückt ob dieses Bildes. Bis die Verzückung nach einigen Tagen nachließ und ich mich fragen konnte: Was hat nur das Internet mit DRM zu tun? Richtiger muss es doch heißen: … dem Senfgas des Buchmarkts!

Ich habe der Ursache der lähmenden und alsbald nachlassenden Verzückung einen Namen gegeben: es ist der Romantische Nebel des Buchmarkts (RNB).

Woran erkennt man den RNB? Das ist ja das Schwierige. Er vernebelt auf geniale Weise. Aber ein sicheres Indiz für das Vorhandensein des RNB ist, dass sich der Autor an Amazon abmüht. Denn jedem außerhalb des Buchmarkts ist klar: Amazon is shipping goods. Buchmarkt und Amazon basieren auf dem selben Geschäftsmodell. Es ist, als ob zwei Verkäufer der Katze im Sack über die Beschaffenheit des Sackes fachsimpeln.

Ist der RNB etwas Schlimmes? Nein, er ist romantisch, unterhaltsam und inspirierend – wie jede Innenansicht. Außerdem reisen manche mit Nebelhörnern durchs Land und dürfen vor einem Publikum vortragen, die den RNB schlichtweg für den Nebel des Grauens halten. Auf diese Idee muss man erstmal kommen!

Wo immer ich den Romantischen Nebel des Buchmarkts vermute, lasse ich ein paar Tage verstreichen, bis der Nebel sich legt. Dann durchstöbere ich die Zuschriften zu z.B. den Allgemeinen Feststellungen zur Buchsituation nach unbeantworteten Kommentaren. Das sind die Außenansichten zur Buchsituation. Es funktioniert! Nach der romantischen Unterhaltung folgt nun die Inspiration.

16 Sep 11 Einbinden der Dita4Publishers-DTDs in XMLSpy und XMLMind

Als Quellcode-Editor nutze ich Altova XMLSpy. Als WYSIWYG-Editor XMLMind.  Bei allen anderen XML-Editoren wird es sich jedoch ähnlich verhalten. Es gilt hauptsächlich, die DITA-Catalog-Datei in die Catalogdatei des jeweiligen Editors einzubinden. Darum habe ich das eBook Dita4Publishers – von Eliot Kimber um ein Kapitel erweitert. Darin finden Sie eine Anleitung, wie Sie pubmap.dtd, article.dtd und weitere Document Type Definitions in XMLSpy einbinden und lokal nutzen können. Ein zweites Kapitel beschreibt das Einbinden der DTDs in XMLMind. Leider scheint das Programm noch keine Cataloge zu unterstützen. So fällt das Einbinden recht arbeitsintensiv aus. Aber ich bin ein Fan des Programms, weil es das Nutzen des Conref-Mechanismus´ so einfach macht.

Dieser Artikel ist im kostenlosen eBook Ditalog als EPUB und PDF-Datei verfügbar.

30 Mai 11 Unterversorgung der Dokumentation?

Fristet im Software-Unternehmen die Technische Dokumentation das Leben eines unterversorgten Patienten? Vorschläge an die Redakteure und Geschäftsführer für die Zeit bis zur nächsten Visite.

Sie können diesen Artikel als eBook (EPUB) oder PDF-Datei downloaden.

Innovation immer mit Gewinn?

Vorigen Sommer verschlug es meine Familie wieder in den Freizeitpark IKEA. Ein Abstecher in den Sanitärbereich des Restaurants ließ mich schmunzeln: die Nachbartür war mit etwas mehr Text versehen als meine ersehnte!

Da kann keiner böse sein.

Noch lange habe ich überlegt, warum eine Tür mich zum Schmunzeln bringen konnte. Ich bemühte intellektuelle Konzepte wie Kontext oder Emotion. Immerhin hatte der Verfasser es geschafft, ein Verbot, eine Entschuldigung für eine verschlossene Tür in einen Sympathieträger umzumünzen! Doch nach einigen Tagen war ich dann bereit, es mir einzugestehen. Es war purer Neid! Nicht so sehr auf den Spruch, sondern dass dieser sich auf Tausenden von Türen ausbreiten konnte! Was muss das für eine innovative Geschäftsführung sein, in dessen Biotop nicht nur solche Ideen entstehen, sondern diese auch realisiert werden! Es ist bestimmt weniger aufwendig, für den Kundensupport ein Twitter-Account einzurichten, als Tausende Türen zu kennzeichnen. Trotzdem wird Ihnen Ersteres im Softwareunternehmen nicht so schnell gelingen!

Überall im Netz wird von Technischen Redakteuren die mangelnde Unterstützung für eine professionellere
Dokumentation beklagt. Oft herrscht im Softwareunternehmen die Mentalität des Jeder kann schreibens vor. Ich bildete mir ein, dass eine rudimentäre Technische Redaktion ähnlich zu werten ist wie diese Tür: als Indikator für die Innovationskultur im Unternehmen – also ebenfalls rudimentär. Bis Ute Klingelhöfers Frage Warum sollte man in die Technische Redaktion investieren? die Problematik der Dauerunterversorgung wieder auf die Füße stellte. Dieser Artikel soll Redakteuren helfen, die Gegenwart im Softwareunternehmen zu verstehen und sie befähigen, Ihre Kraft auf innovative Veränderungen in der Zukunft des Unternehmens zu verwenden.

(mehr…)