Spezialisierung: Eigene DITA-Attribute definieren

DITA bietet bereits einige Attribute, die schon sehr viele wichtige Dinge in der technischen Dokumentation abdecken: product, audience, platform seien da als Beispiele genannt.

Wenn es um sehr firmenspezifische Dinge geht, benötigt man hier schnell eigene Attribute. Für mich persönlich sehr wichtig, sind auch vorgegebene Attributwerte, weil eine vorgegebene Auswahl immer sehr viel weniger fehleranfällig ist.

Was bedeutet Spezialisierung?

In DITA nimmt man etwas Vorhandenes, also einen bereits vorhandenen Topictyp (z.B. Concept) oder ein bereits vorhandenes Attribut, und leitet davon seine eigene Version ab: man spezialisiert. Inbesondere in Bezug auf Topictypen ist wichtig zu wissen, dass man Festlegungen der DTD von der man ableitet, nicht „aufweichen“ kann. Wenn ein Element <hups> in der Ur-DTD zwingend erforderlich ist, kann man es in der Spezialisierungs-DTD nicht optional definieren.

Attribute spezialisieren

Es gibts 2 Arten von Attributen, die man spezialisieren kann: props (speziell für Filtern) und base (Sinn und Zweck hat sich mir noch nicht erschlossen…). Da ich mein neues Attribut zum Filtern des Contents benutzen möchte, benutze ich daher das props-Attribut.

Schritt 1: Attribut deklarieren
Ich werde nun ein Attribut definieren, das beschreiben soll, für welchen Hilfekontext das Element gilt: für die Hilfe im Web oder für die Hilfe in der Software.

1. Zuerst erstelle ich eine Datei namens helpContextPropsDomain.ent mit folgendem Inhalt:



   Im ersten Teil lege ich den Namen des Attributs (help-context) fest und in meinem Fall auch 2 vordefinierte Werte (webpage, software).
2. Ich speichere die Datei im dtd-Verzeichnis des DITA-OT ab.

Schritt 2: Attribut der DTD bekannt machen

1. Nun öffne ich die concept.dtd und lege noch eine Sicherheitskopie von ihr unter anderem Namen ab Man weiß nie… ;).
2. Unter dem Bereich DOMAIN ATTRIBUTE DECLARATIONS füge ich ein:
   
SYSTEM "helpContextPropsDomain.ent"
>
%help-context-props-d-dec;
3. Unter dem Bereich DOMAIN ATTRIBUTE EXTENSIONS erweitere ich :
   

4. Unter dem Bereich DOMAINS ATTRIBUTE OVERRIDE erweitere ich :
   
&ui-d-att; &hi-d-att; &pr-d-att; &sw-d-att;
&ut-d-att; &indexing-d-att;&help-context-props-d-att;" >
5. Diese Schritte müssen nun für alle Topictypen wiederhiolt werden, für die man das Attribut braucht.

Schritt 3: testen 🙂

1. Ich erstelle eine XML-Datei auf Grundlage dieser DTD
2. Ich füge das Attribut _help-context=“webpage“_ in ein-Element ein
3. Ich jage das Dokument durch einen Validator – und wenn der nicht meckert, hat es funktioniert

Spezialisierung in XMetal DITA Edition
Der XMetal DITA Edition bindet ein DITA-OT ein. Wie es scheint benutzt er dieses ausschließich zum Generieren.
Die DTDs, die XMetal benutzt, liegen im Programmverzeichnis unter „…XMetaL 5\Author\DITA\DITA_OT_DTD\“<.

1. D.h. die oben erstellten bzw. bearbeiteten Dateien müss dort hinein kopiert werden.
2. XMetal neu starten
3. Ein Concept anlegen
4. Und sich freuen, dass man ein neues Attribut im Attribute Inspector sieht 🙂

Mehr zum Thema
In Eliot Kimbers Tutorial erfahrt ihr mehr zur Spezialisierung.