Inhalte in Topics auszeichnen

(Auszug aus "DITA - Der neue Standard für Technische Dokumentation" von Johannes Hentrich)

Neben den Struktur-Elementen zur Definition der einzelnen Topictypen stellt DITA zahlreiche Elemente zur semantischen und typografischen Auszeichnung bereit. Die für diesen Zweck bestimmten Elemente werden thematisch in Domains zusammengefasst. Mit der DITA Version 1.1 stehen sieben Domains zur Verfügung, deren thematischer Schwerpunkt auf der semantischen Auszeichnung von Inhalten aus der Software-Dokumentation liegt. Um diese Einseitigkeit aufzuheben und auch um weitere thematische Gebiete zu erschließen, gibt es inzwischen zahlreiche OASIS-Arbeitsgruppen, die Domains entwickeln, deren semantische Auszeichnungen sich nicht auf die Software-Dokumenta-tion beschränken. Genannt sei hier zum Beispiel das DITA Machine Industry Specialization Subcommittee, welches die Belange der Maschinenbau-Industrie in DITA berücksichtigt wissen will.

Im Folgenden wird ausführlich auf die einzelnen Domains und ihre Möglichkeiten der semantischen Auszeichnungen eingegangen. Zum Abschluss dieses Abschnitts werden dann auch noch die Möglichkeiten für die typografischen Auszeichnungen vorgestellt.

programming-Domain

Mit den Elementen der programming-Domain können Sie die Syntax einer Programmiersprache und Programmierbeispiele auszeichnen. Dabei finden sich auch verschachtelte Elemente, wie zum Beispiel das <parml>-Element oder das <syntaxdiagram>-Element, die weitere Elemente zur semantischen Auszeichnung enthalten.

In der folgenden Liste sind die Elemente der programming-Domain aufgeführt:

  • <apiname>: Zeichnet den Klassennamen oder Methodennamen einer API (Application Programming Interface) aus.
  • <codeblock>: Zeichnet den Programmcode in einem Listing aus.
  • <codeph>: Zeichnet Codeschnipsel innerhalb des Texts aus.
  • <delim>: Element zur Auszeichnung eines Zeichens, das zur Begrenzung von Programmcodes oder einer speziellen Syntax dient.
  • <fragment>: Zeichnet eine Teilmenge einer Programmiersyntax aus.
  • <fragref>: Stellt eine Referenz zu einem Syntaxfragment her. Müssen bestimmte Syntaxdefinitionen häufig verwendet werden, empfiehlt sich die Verwendung einer solchen Referenz.
  • <groupseq>: Zeichnet in einem Syntaxdiagramm Gruppen von Schlüsselwörtern (<kwd>-Element) und/oder Variablen (<var>-Element) aus. Wird innerhalb des <syntaxdiagram>-Elements verwendet.
<syntaxdiagram>
    <groupseq>
        <var>include-name</var>
        <kwd>INCLUDE</kwd>
    </groupseq>
</syntaxdiagram>
  • <groupchoice>: Zeichnet in einem Syntaxdiagramm Teile der Syntax aus, bei der der Nutzer eine Auswahl treffen muss. Wird innerhalb des <syntaxdiagram>-Elements verwendet.
  • <groupcomp>: Zeichnet in einem Syntaxdiagramm Teile der Syntax aus, die zusammengehören und entsprechend formatiert werden sollen.
  • <kwd>: Zeichnet ein Schlüsselwort in einem Syntaxdiagramm aus.
  • <oper>: Zeichnet einen Operator aus.
  • <option>: Zeichnet bei einem Befehl eine mögliche Option aus.
  • <parmname>: Zeichnet den Parameter einer API aus.
  • <parml>: Zeichnet eine Liste mit Parametern aus. Enthält die Elemente <plentry>, <pt> und <pd>.
<parml>
    <plentry>
        <pt>n</pt>
        <pd>First counter for loop.</pd>
    </plentry>
    <plentry>
        <pt>m</pt>
        <pd>Second counter for loop.</pd>
    </plentry>
</parml>
  • <pd>: Zeichnet die Definition oder die Beschreibung eines Parameters in einer Parameterliste aus.
  • <pt>: Zeichnet einen Parameter in einer Parameterliste aus.
  • <plentry>: Enthält das <pt>-Element und das <pd>-Element zur Auszeichnung von Parametern in einer Parameterliste (<paraml>-Element).
  • <repsep>: Zeichnet in einem Syntaxdiagramm Elemente aus, die sich wiederholen.
  • <sep>: Zeichnet einen Trenner in einer Syntax aus.
  • <synblk>: Zeichnet einen Syntaxblock aus.
  • <synnote>: Zeichnet eine Bemerkung in einem Syntaxdiagramm aus. Wird innerhalb des <syntaxdiagram>-Elements verwendet.
  • <synnoteref>: Referenziert ein <synnote>-Element, das bereits in einem Syntaxdiagramm definiert wurde.
  • <synph>: Enthält Elemente zur Auszeichnung von Syntaxdefinitionen, wie zum Beispiel das <kwd>-Element und das <var>-Element.
<synph>
    <var>include-name</var>
    <kwd>INCLUDE</kwd>
</synph>
  • <syntaxdiagram>: Zeichnet ein Syntaxdiagramm aus. Das <syntaxdiagram>-Element enthält die Elemente <title>, <groupseq>, <groupcomp>, <groupchoice>, <fragref>, <fragment>, <repsep>, <synblk>, <synnote> und <synnoteref>.
  • <var>: Zeichnet eine Variable in einem Syntaxdiagramm aus.

software-Domain

Mit den Elementen der software-Domain werden Operationen eines Softwareprogramms ausgezeichnet.

Folgende Elemente enthält die software-Domain:

  • <cmdname>: Zeichnet den Namen eines Befehls eines Softwareprogramms aus.
  • <filepath>: Zeichnet den Pfad zu einer Datei aus.
  • <msgblock>: Zeichnet den Text von mehreren Nachrichten aus, die ein Softwareprogramm ausgibt.
  • <msgnum>: Zeichnet die Nummer einer Nachricht aus, die ein Softwareprogramm ausgibt.
  • <msgph>: Zeichnet den Text einer Nachricht aus, die ein Softwareprogramm ausgibt.
  • <systemoutput>: Zeichnet die Ausgabe zu einem Befehl aus.
  • <userinput>: Zeichnet die Eingabe des Nutzers aus, wenn damit das Softwareprogramm gesteuert wird.
  • <varname>: Zeichnet einen Variablennamen aus, welche das Softwareprogramm benötigt.

user interface-Domain

Alles was der Nutzer im Interface erkennen kann, wird mit den Elementen der user interface-Domain ausgezeichnet. Dazu stehen die folgenden Elemente zur Verfügung:

  • <menucascade>: Zeichnet eine Auswahl von Menüeinträgen aus. Jeder einzelne Menüeintrag wird dabei mit einem <uicontrol>-Element erfasst.
<menucascade>
    <uicontrol>Datei</uicontrol>
    <uicontrol>Neu</uicontrol>
    <uicontrol>Öffnen</uicontrol>
    <uicontrol>Speichern</uicontrol>
    <uicontrol>Schließen</uicontrol>
</menucascade>
  • <screen>: Eine textliche Repräsentation eines Bildschirms wird mit diesem Element ausgezeichnet. Vor allem für Programme, die keine GUI (Graphical User Interface) aufweisen, ist dieses Element gedacht.
  • <shortcut>: Zeichnet eine Tastenkombination aus.
  • <uicontrol>: Zeichnet alle Elemente einer GUI aus, mit denen der Nutzer das Programm bedienen kann.
  • <wintitle>: Zeichnet den Titel von Fenstern oder Dialogfenstern aus.

utilities-Domain

Mit den Elementen einer utilities-Domain kann eine Image-Map definiert werden. In einer Image-Map werden unterschiedliche Bereiche definiert, die verlinkt werden. Image-Maps sind bereits aus HTML bekannt, jedoch unterscheidet sich die Definition einer Image-Map in DITA ein wenig von der Definition einer Image-Map in HTML.

Das folgende Beispiel zeigt, wie eine Image-Map in DITA definiert wird:

<imagemap>
    <image href="diagramm.jpg"></image>
    <area>
        <shape>poly</shape>
        <coords>0,0,53,83</coords>
        <xref href="area_1.xml"></xref>
    </area>
    <area>
        <shape>poly</shape>
        <coords>54,0,117,90</coords>
        <xref href="area_2.xml"></xref>
    </area>
    <area>
        <shape>poly</shape>
        <coords>104,0,14,121</coords>
        <xref href="area_3.xml"></xref>
    </area>
</imagemap>

Im <imagemap>-Element wird die Image-Map definiert. Die Grafik, auf die sich die Image-Map bezieht, wird im <image>-Element angegeben.

In den <area>-Elementen werden die einzelnen Bereiche einer Image-Map definiert.

Dabei wird im <shape>-Element angegeben, um was für einen Bereich es sich handelt. Mögliche Werte sind rect (Rechteck), circle (Kreis), poly (Polygon) und default, welches den Bereich der gesamten Grafik umfasst.

Im <coords>-Element sind die Koordinaten der zu verlinkenden Bereiche anzugeben. Der Nullpunkt liegt dabei links oben. Gemessen wird in Pixeln.

Im <xref>-Element wird schließlich im href-Attribut die Zielandresse angegeben, die aufgerufen werden soll, wenn der Nutzer den verlinkten Bereich angeklickt hat.

xNAL-Domain

Die xNAL-Domain verwendet eine Teilmenge der Elemente der Extensible
Name and Address Language, mit der Adressinformationen erfasst werden können. Die Adressinformationen können sowohl in Topics als auch in Maps hinterlegt werden.

Die xNAL-Domain verwendet die folgenden Elemente der Extensible Name and Address Language:

  • <authorinformation>: Dieses Element ist ein Container-Element, welches das <personinfo>-Element und das <organization>-Element enthalten kann. Diese Elemente enthalten wiederum weitere Elemente mit Informationen zum Autor oder zum Unternehmen.
<authorinformation>
    <personinfo>
        ...
    </personinfo>
    <organizationinfo>
        ...
    </organizationinfo>
</authorinformation>
  • <addressdetails>: Dieses Element ist ein Container-Element, welches die Elemente <administrativearea>, <country>, <locality> und <thoroughfare> zur Erfassung von Adressinformationen enthält.
<addressdetails>
    <thoroughfare>Pflegerstraße 40</thoroughfare>
    <locality>
        <localityname>München</localityname>
        <postalcode>81427</postalcode>
    </locality>
    <administrativearea>Bayern</administrativearea>
    <country>Deutschland</country>
</addressdetails>
  • <administrativearea>: Enthält Informationen zum Bundesland oder Bundestaat.
  • <contactnumber>: Enthält Informationen zur Telefon- und Faxnummer.
  • <contactnumbers>: Enthält <contactnumer>-Elemente.
<contactnumbers>
    <contactnumer>089 98161590</contactnumber>
    <contactnumber>089 81009233</contactnumer>
</contactnumbers>
  • <country>: Enthält den Namen des Landes.
  • <emailaddress>: Enthält eine E-Mail-Adresse.
  • <emailaddresses>: Enthält <emailaddress>-Elemente.
<emailaddresses>
    <emailaddress>jhentrich@xlcontent.de</emailaddress>
</emailddresses>
  • <firstname>: Enthält den Vornamen.
  • <generationidentifier>: Enthält Informationen zur Generation der Person, zum Beispiel Jr.
  • <honorific>: Enthält den Titel der Person.
  • <lastname>: Enthält den Nachnamen.
  • <locality>: Enthält das <localityname>-Element und das <postalcode>-Element.
<locality>
    <localityname>München</localityname>
    <postalcode>81427</postalcode>
</locality>
  • <localityname>: Enthält den Stadtnamen.
  • <middlename>: Enthält den zweiten Vornamen.
  • <namedetails>: Enthält das <personname>-Element und/oder das <organizationnamedetails>-Element.
  • <organizationinfo>: Dieses Element ist ein Container-Element, welches die Elemente <namedetails>, <addressdetails>, <contactnumbers>, <email-addresses> und <urls> enthält.
<organizationinfo>
    <namedetails>...</namedetails>
    <addressdetails>...</addressdetails>
    <contactnumbers>...</contactnumbers>
    <emailaddresses>...</emailaddresses>
    <urls>....</urls>
</organizationinfo> 
  • <organizationname>: Enthält den Namen eines Unternehmens oder einer Organisation.
  • <organizationnamedetails>: Dieses Element ist ein Container-Element, welches die Elemente <organizationname> und <otherinfo> enthält.
<organizationdetails>
    <organizationname>XLcontent Verlag</organizationname>
    <otherinfo>Verlag für Kommunikation und Technik</otherinfo>
</organizationdetails>
  • <otherinfo>: Enthält zusätzliche Informationen zur Person oder Organisation.
  • <personinfo>: Dieses Element ist ein Container-Element, welches die Elemente <namedetails>, <addressdetails>, <contactnumbers> und <email-addresses> enthält.
<personinfo>
    <namedetails>...</namedetails>
    <addressdetails>...</addressdetails>
    <contactnumbers>...</contactnumbers>
    <emailaddresses>...</emailaddresses>
</personinfo>
  • <personname>: Dieses Element ist ein Container-Element, welches die Elemente <firstname>, <middlename>, <lastname>, <generationidentifier> und <otherinfo> enthält.
<personname>
    <firstname>Johannes</firstname>
    <middlename></middlename>
    <lastname>Hentrich</lastname>
    <generationidentifier></generationidentifier>
    <otherinfo>Autor</otherinfo>
</personname>
  • <postalcode>: Enthält die Postleitzahl.
  • <thoroughfare>: Enthält Informationen zur Straße.
  • <url>: Enthält eine URL.
  • <urls>: Enthält <url>-Elemente.
<urls>
    <url>www.xlcontent-verlag.de</url>
</urls>

Typografische Auszeichnungen

Die Elemente für die typografischen Auszeichnungen befinden sich in der highlighting-Domain. Typografische Auszeichnungen sollten Sie nur dann verwenden, wenn kein semantisches Element für die gewünschte Auszeichnung zur Verfügung steht und mit der Auszeichnung tatsächlich nur ein optischer Effekt erzielt werden soll.

In der highlighting-Domain sind folgende Elemente definiert:

  • <b>: Setzt den Inhalt in Fettschrift.
  • <i>: Setzt den Inhalt in Kursivschrift.
  • <u>: Unterstreicht den Inhalt.
  • <tt>: Setzt den Inhalt in eine nichtproportionale Schrift, wie zum Beispiel in Courier New.
  • <sub>: Setzt den Inhalt tiefer.
  • <sup>: Setzt den Inhalt höher.

  

<< zurück vor >>

 

 

 

Tipp der data2type-Redaktion:
Zum Thema DITA bieten wir auch folgende Schulungen zur Vertiefung und professionellen Fortbildung an:

Copyright © 2008 XLcontent Verlag
Für Ihren privaten Gebrauch dürfen Sie die Online-Version ausdrucken.
Ansonsten unterliegt dieses Kapitel aus dem Buch "DITA - Der neue Standard für Technische Dokumentation" denselben Bestimmungen, wie die gebundene Ausgabe: Das Werk einschließlich aller seiner Teile ist urheberrechtlich geschützt. Alle Rechte vorbehalten einschließlich der Vervielfältigung, Übersetzung, Mikroverfilmung sowie Einspeicherung und Verarbeitung in elektronischen Systemen.

XLcontent Verlag, Pflegerstraße 40, 81247 München