3.5.2  DITA Inhaltsmodell

An dieser Stelle sei kurz auf das umfangreiche Inhaltsmodell von DITA in Form von XML Schnippseln eingegangen. Gerade soviel DITA wie nötig ist, um mit Tektur CCMS arbeiten zu können.

3.5.2.1  Inlineelemente

Buchwelt DITA
Paragraph
Paras erlauben die gängigen Inlineelemente, z.B. <b> , <i> , <u> , <sup> , <sub> , und werden mittels <p> Tag ausgezeichnet.
<p>Das ist ein Para mit <b>fettem</b> und <i>kursiven</i> Text, 
   sowie mit hochgestellter<sup>Quadratzahl</sup> und 
   tiefgestellter<sub>Zahlenuntergrenze</sub>.
</p>
Fußnote
Fußnoten werden mittels <fn> Tag ausgezeichnet. Das Attribut @callout ist optional und gibt den Fußnotenschlüssel an. Ohne Angabe wird die Fußnote meist fortlaufend nummeriert.
<fn callout="#1">
    Das ist Text in einer Fußnote. Hier sind auch Links erlaubt 
    <link href="http://www.tekturcms.de">Tektur Homepage</link>
</fn>
Link
Links können sowohl extern auf eine Ressource im Internet verweisen, aber auch intern auf einen anderen Topic. Hierbei würde die Syntax so aussehen:
<link href="#topicid" format="dita">Link auf anderen Topic</link>
Indexeintrag
Indexeinträge werden mit dem <indexterm> Element ausgezeichnet. Sie können u.a. direkt im Content vorkommen und bei Tektur CCMS auch einen verschachtelten Untereintrag aufweisen.
<indexterm>Verarbeitungsmethoden
<indexterm>Vortransformation</indexterm></indexterm>
Icon
Inzeilige Icons können über das Element <image> bedatet werden.
<p>Jetzt kommt ein Icon <image href="icon.png"/>.</p>
Code
Inzeilige Codeschnippsel oder Dateipfade, etc. werden über das Element <codeph> gesetzt.
<p>Windows Fonts Ordner: <codeph>C:\Windows\Fonts</codeph>.

3.5.2.2  Blockelemente

Buchwelt DITA
Grafik
Die Grafik kann seitenbreit, spaltenbreit oder in der Marginalie angebracht werden. Das wird in Tektur CCMS über das Attribut @expanse gesteuert.
<fig expanse="column" frame="all" scale="50">
    <image href="Cormorant.svg"/>
</fig>
Quelltext
Quelltexte oder vorformatierter Text können einerseits inzeilig über das <codeph> Element bedatet werden oder als Blockelement mittels des <pre> Elements.
<pre xml:space="preserve">
for i in range(10):
  print i
</pre>
Warnhinweis
Warnhinweise werden mittels des Elements <hazardstatement> bedatet. Es gibt vier verschiedene Ausprägungen:
  • warning
  • danger
  • caution
  • notice
Diese wird über das Attribut @type gesteuert.
<hazardstatement type="warning">
    <messagepanel>
        <typeofhazard>
            Heisse Flächen sollte nicht berührt werden.
        </typeofhazard>
        <howtoavoid>Warnschilder anbringen</howtoavoid>
        <howtoavoid>Temperaturregler einschalten</howtoavoid>    
    </messagepanel>
</hazardstatement>
Der Beschreibung der Gefahrenstelle <typeofhazard> können dabei mehrere Maßnahmen ( <howtoavoid ) folgen.
Hinweis
Der einfache Hinweis wird über das Element <note> bedatet.
<note>
    <p>Ohne weitere Maßnahmen werden Dokumente
       mit den Rechten des Erzeugers versehen.</p>
</note>
Listen
Es stehen geordnete, ungeordnete und Definitionslisten zur Verfügung. <ul> und <ol> Listen können analog zu bspw. HTML gesetzt werden. Zusätzlich erlaubt DITA auch Paras in Listenpunkten. Die folgenden Beispiele sind von der DITA Dokupage ↗:
<ol>
    <li>Red</li>
    <li>Orange</li>
    <li><p>Yellow</p></li>
    <li>Green</li>
    <li>Blue</li>
    <li>Indigo</li>
    <li>Violet</li>
</ol>
<ul>
    <li>This is an item in an unordered list.</li>
    <li>To separate it from other items in the list, 
        the formatter puts a bullet beside it.</li>
     <li>The following paragraph, contained in the list item
         element, is part of the list item which contains it.
         <p>This is the contained paragraph.</p>
     </li>
     <li>This is the last list item in our unordered list.</li>
</ul>
Außerdem steht noch die Definitionsliste <dl> zur Verfügung mit der auch dieses Kapitel realisiert ist:
<dl>
    <dlhead>
        <dthd>Image File View Selection</dthd>
        <ddhd>Resulting Information</ddhd>
    </dlhead>
    <dlentry>
        <dt>File Type</dt>
        <dd>Image's file extension</dd>
    </dlentry>
    <dlentry>
        <dt>Image Class</dt>
        <dd>Image is raster, vector, metafile or 3D</dd>
    </dlentry>
    <dlentry>
        <dt>Number of pages</dt>
        <dd>Number of pages in the image</dd>
    </dlentry>
    <dlentry>
        <dt>Fonts</dt>
        <dd>Fonts contained within a vector image</dd>
    </dlentry>
</dl>

3.5.2.3  Strukturelemente

Buchwelt DITA
Kapitel
Ein Topic sollte eine in sich abgeschlossene Informationseinheit bilden, die in verschiedenen Kontexten eingebunden werden kann.
<topic>
  <title>Der Titel des Topics</title>
  <body>
    <p>Ein einleitender Satz vor der Grafik</p>
    <fig>
      <image href="schöne_grafik.svg"/>
    </fig>
    <p>Ein abschliessender Satz zum Topic</p>
  </body>
</topic>
Abschnitt
Eine Section ist ein Abschnitt mit einer Unterüberschrift innerhalb eines Topics.
<section>
  <title>Unterabschnitt</title>
  <p>Blockelemente, wie Paras, folgen direkt dem Titel</p>
</section>
Kapitelstruktur
Die Kapitelstruktur wird in DITA mittels einer verschachtelten Topic-Struktur definiert, die sogenannte DITA Map. Hierbei werden <topicref> Elemente verwendet, die mittels des Attributs @href auf vorhandene Topics verweisen. Die Titel der einzelnen Topics sind im Attribut @navtitle zur Erzeugung des Inhaltsverzeichnisses vorgehalten.
<?xml version="1.0" encoding="utf-8"?>
<map title="XML Entwicklerhandbuch">
   <topicmeta>
      <navtitle>XSLT - XQuery - MarkLogic</navtitle>
      <shortdesc/>
      <keywords>
         <keyword>XML</keyword>
         <keyword>XSLT</keyword>
         <keyword>XQUERY</keyword>
      </keywords>
   </topicmeta>
   <topicref href="1_Intro.dita" navtitle="Intro"/>
   <topicref href="2_Anwendungsgebiete.dita"
      navtitle="Anwendungsgebiete">
      <topicref 
      href="2_1_XSLT___die_Programmiersprache_im_XML_Bereich.dita"
      navtitle="XSLT - die Programmiersprache im XML Bereich"/>
      <topicref 
      href="2_2_Aktuelle_und_vergangene_Anwendungen.dita"
      navtitle="Aktuelle und vergangene Anwendungen"/>
[...]

3.5.2.4  Taskelemente

Das Element task beschreibt eine Handlungsanweisung oder Prozedur. Da es sehr komplex ist, wird dafür eine separate section in diesem Buch reserviert.
Ein gut ausgefüllter Task mit jeweils nur einem Kindelement ist im folgenden als XML Schnippsel dargestellt. Natürlich sind in den Elementen an bestimmten Stellen noch weitere Blockelemente erlaubt, wie Warnhinweise, Listen, Tabellen, etc.
<task>
    <title>Ein Task</title>
    <abstract>
        <p>Abstract-Element in Task</p>
    </abstract>
    <taskbody>
        <prereq>
            <p>Prereq-Element in Task</p>
        </prereq>
        <context>
            <p>Context-Element in Task</p>
        </context>
        <steps>
            <stepsection>
                <p>Stepsection-Element in Task</p>
            </stepsection>
            <step>
                <cmd>Cmd-Element in Step</cmd>
                <substeps>
                    <substep>
                        <cmd>Substep-Element in Step</cmd>
                        <info>
                            <p>Info-Element in Substep</p>
                        </info>
                        <stepresult>
                            <p>Stepresult-Element in Substep</p>
                        </stepresult>
                    </substep>
                </substeps>
                <choices>
                    <choice>
                        <p>Choice-Element in Step</p>
                    </choice>
                    <choice>
                        <p>Zweites Choice-Element in Step</p>
                    </choice>
                </choices>
                <choicetable>
                    <chhead>
                        <choptionhd>
                            <p>Choicetable mit leeren Zellen in Step</p>
                        </choptionhd>
                        <chdeschd/>
                    </chhead>
                    <chrow>
                        <choption/>
                        <chdesc/>
                    </chrow>
                </choicetable>
                <info>
                    <p>Info-Element in Step</p>
                </info>
                <stepresult>
                    <p>Stepresult-Element in Step</p>
                </stepresult>
            </step>
        </steps>
        <result>
            <p>Result-Element in Task</p>
        </result>
        <postreq>
            <p>Postreq-Element in task</p>
        </postreq>
    </taskbody>
</task>
Aus diesem XML Schnippsel kann man sich leicht die zugrundeliegende Grammatik als Grafik erzeugen lassen, z.B. mit dem oXygen XML Editor. (Da es sich um eine SVG Grafik handelt, sollte man auf einem Rechner verlustfrei reinzoomen können)
Buchwelt DITA
Einleitung
Das <abstract> Element kann weitere Blockelemente beinhalten und dient zur initialen Beschreibung der Handlungsanweisung, Prozesses oder der Prozedur (Ich hoffe, dass ich alle in diesem Kontext relevanten Synonyme aufgezählt habe)
Vorbedingung
Im Rumpf der Task taskbody können Vorbedingungen angegeben werden, die erfüllt sein müssen bevor die Handlungsanweisung ausgeführt werden kann. In diesem prereq Element sind wieder weitere Blockelemente, wie Listen und Tabellen erlaubt. Natürlich sollte in der Ausgabe dieser Abschnitt irgendwie gekennzeichnet sein - so wie auch alle anderen Elemente - um diesen vom Fließtext zu unterscheiden.
Kontext
Im <context> Element wird beschrieben in welchem Kontext (Umgebung, Zweck und Nutzen) die Handlungsprozedur ausgeführt werden soll. Hier sind auch wieder viele Blockelemente erlaubt.
Inhalt der Arbeitsschritte
Schlussendlich hat man auch noch im <steps> Element die Möglichkeit weiteren Kapitelinhalt einzugeben - über das <stepsection> Element.
Arbeitsschritt
Das <step> Element selbst hat im einfachsten Fall ein <substeps> Element, so dass eine einfache verschachtelte nummerierte Liste abgebildet werden kann.
<step>
    <cmd>Cmd-Element in Step</cmd>
    <substeps>
        <substep>
            <cmd>Substep-Element in Step</cmd>
            <info>
                <p>Info-Element in Substep</p>
            </info>
            <stepresult>
                <p>Stepresult-Element in Substep</p>
            </stepresult>
        </substep>
    </substeps>
    [...]
Im <cmd> Element steht dabei die auszuführende Aktion, während andere Elemente die Aktion weiter präzisieren. Besonders interessant ist dabei, dass z.B. Warnhinweise ( <hazardstatement> ) immer vor dem <cmd> Element bedatet werden müssen. Im <info> Element können zusätzliche Informationen stehen. Der <stepresult> dokumentiert schließlich das Ergebnis des Arbeitsschritts.
Auswahl der Aktionen
Hat der Ausführende des Handlungsschritts mehrere Optionen für die Aktion, dann kann das mittels des Elements <choices> modelliert werden. Statt einer Liste steht auch eine tabellarische Darstellung ( <choicetable> ) zur Verfügung, die neben der Aktion ( <choption> ) auch noch eine Beschreibung ( <chdesc> ) derselben erlaubt.
<choices>
    <choice>
        <p>Choice-Element in Step</p>
    </choice>
    <choice>
        <p>Zweites Choice-Element in Step</p>
    </choice>
</choices>
<choicetable>
    <chhead>
        <choptionhd>
            <p>Choicetable mit leeren Zellen in Step</p>
        </choptionhd>
        <chdeschd/>
    </chhead>
    <chrow>
        <choption/>
        <chdesc/>
    </chrow>
</choicetable>
Ergebnis der Handlungsanweisung
Werden alle Arbeitsschritte ausgeführt, dann sollte ein Ergebnis ( <result> ) dokumentiert werden. Diese Ergebnis-Elemente stehen auch im <step> und <substep> Element als <stepresult> Element zur Verfügung.
Nachbedingung
Analog zur Vorbedingung der Task kann auch eine Nachbedingung über das Element <postreq> dokumentiert werden.
Previous PageNext Page
Map Version: