Grundgerüst
<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<?xml-stylesheet href="documl.xsl" type="text/xsl"?>
<article name="Angezeigter Artikelname" id="artikelid">
<s name="Abschnittsname" a="Ankername" >
Hallo Welt
</s>
</article>
Das ist das Beispiel eines extrem simpel gestrickten Artikels. Er besteht aus
der Angabe, dass es sich um eine XML-Datei handelt, dem Einbinden des
docuML-Stylesheets, Einem Tag "article" mit dem (muss-)Attribut name und id.
Wichtig ist, dass jede Datei zusätzlich in der project.xml eingetragen wird, und
dass das dortige "id"-Attribt dem id-Attribut in der Artikeldatei entspricht,
ansonsten wird findet die Transfomation die nächste/vorige Datei beim
Zusammenhängen der Dateien (Link zur nächsten und vorigen Datei) nicht.
Das "s"-Tag (Section, also Abschnitt. p wie Paragraph ist schon an das XHTML-p
vergeben) ist an sich optional, es macht jedoch meist nur in einer Indexdatei Sinn,
keinen Abschnitt zu definieren.
Abschnittsüberschriften auflisten
Mit dem Tag links können Sie alle Abschnittsüberschriften mit Links zu den
entsprechenden Abschnitten auflisten. Die docuML-Transformation
geht dabei davon aus, dass Sie einen "schönen Dateikopf" haben möchten
und bindet das entsprechende Logo (in project.xml definiert) ein.
Dieses Tag sollte nicht selst in einem Abschnitt stehen. Eine
um Einiges schönere Datei erhalten Sie also einfach durch Einfügen des
Links-Tag:
<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<?xml-stylesheet href="documl.xsl" type="text/xsl"?>
<article name="Angezeigter Artikelname" id="artikelid">
<links/>
<s name="Abschnittsname" a="Ankername" >
Hallo Welt
</s>
</article>
Inhaltsverzeichnis
Ein Inhaltsverzeichnis mit allen Dateien lassen Sie mit dem Tag <listtoc/>
anzeigen. Dabei werden alle Dateien angezeigt, die in project.xml angegeben sind
und zwar mit den Beschreibungen, die in den Dateien selbst angegeben sind
(dem name-Atttribut des article-Tags).
Referenz
Eine Referenz können Sie mit dem Tag <listref/> ausgeben. Dabei werden
alle "reference"-Tags aus allen Dateien, die in project.xml angegeben sind,
mit deren Name ausgegeben; dabei werden sie einmal nach Stichwort und einmal
nach Datei sortiert. Dabei verweisen die Links auf den Abschnitt, in dem der
reference-Tag steht, nicht auf die tatsächliche Stelle der Referenz.
Beispiele
Sie können in Ihren Texten Beispiele speziell markieren, indem Sie das
<example>-Tag (auch die Abkürzung: <ex>-Tag) verwenden.
<example>
Ein Bespiel eines Beispiels...
Nebenbei wird das Beispiel natürlich so angezeigt, wie Ihr Beispiel
auch aussehen würde (z.B. Konstanter Buchstabenabstand)
</example>
Beispiele im Text
Innerhalb des Fließtextes können Sie Ihr Beispiel ohne Zeilenumbrüche mit
inlineexample darstellen. Das sieht dann etwa so aus.
Verwenden Sie dafür das <inlineexample>-Tag, oder die
Abkürzung, <inex>.
Beispiel:
Ein Text sollte bei äußerst kleinen <inlineexample>Beispielen</inlineexample> nicht umbrechen.
Übungen mit Multiple Choice
Sie können Übungen definieren, die per Javascript abgefragt werden, wenn in
der project.xml nicht Druckversion angegeben ist (bei Druckversionen wird
eine Lösungszeile ausgegeben). Dazu verwenden Sie das Tag <exercise>,
mit question und answer.
<exercise type="multiplechoice" clue="true" numanswers="3">
<hint>Der korrekte Wert ist das Ergebnis aus a modulo 3</hint>
<question>Wenn a mit 5 belegt ist, welchen Wert hat
a nach der Operation a%=3</question>
<answer correct="true">2</answer>
<answer correct="false">0</answer>
<answer correct="false">15</answer>
<answer correct="false">8</answer>
</exercise>
Aufgabe 1:
Der Typ kann derzeit
multiplechoice oder
gaptext sein, das
hint-Tag zeigt einen Hinweis auf die richtige Antwort, wenn eine falsche
Antwort angeklickt wurde. Beachten Sie, dass es hint sowohl als
Tag innerhalb der question als auch als Attribut innerhalb der answer-Tags
geben kann. Bei der Tag-Version wird der Hint wird bei jeder falschen
Antwort gezeigt, bei der Attribut-Version nur der jeweilige Link der
Antwort angezeigt, die nicht korrekt beantwortet wurde.
Sind für alle Antworten hints angegeben, wird jeder Hint ausgegeben, wenn
eine Antwort angekreuzt wurde, die nicht hätte angekreuzt werden sollen, und
wenn eine Antwort nicht angekreuzt wurde, die als korrekt markiert ist.
Das Attribut "hint" zeigt bei Multiple Choice, wie viele Kreuze vom Anwender
erwartet werden. Es können mehrere answers correct=(true|false) sein.
Übungen mit Lückentext
Lückentexte können Sie ebenfalls per Javascript abfragen, in dem Fall
schreiben Sie einfach den Lückentext in das exercise-Tag und verwenden
answer-Tags wo Lücken entstehen sollen.
<exercise type="gaptext" clue="true">
Hallo dies ist ein <answer hint="Anderes Wort für Übung" correct="Test"/>
</exercise>
Aufgabe 1:
hier bedeutet clue (optional), dass die Länge des Eingabefeldes anzeigt, wie
viele Zeichen erwartet werden (ansonsten weist es eine Standardlänge auf und
akzeptiert beliebig viele Zeichen). Es versteht sich (und stehta uch so im Beispiel),
dass das correct-Attribut hier andere Werte als true und false annehmen darf.
Hint ist wieder optional und auch als Tag möglich.
Download-Links
Einen Downloadlink auf das in project.xml spezifizierte Ziel können Sie durch
das Tag downloadlink einfügen. Der Grund für ein spezielles Tag ist, dass in
der project.xml ebenfalls geregelt sein kann, ob es sich um die Onlineversion handelt
oder nicht - und der downloadlink ist nur in der Onlineversion sichtbar.
<downloadlink/>
Download dieses Tutorials
Version
Ebenfalls in der project.xml liegt zentral die Versionsnummer des Dokumentes
- bei diesem Dokument nebenbei 3.2, 30.07.2007.
<version/>
HTML in docuML
Sie können XHTML in docuML-Dokumenten auf zwei Arten einbinden - mit Namespaces
oder indem Sie die Tags direkt in die Datei schreiben.
Genau genommen gibt es nicht einmal einen eigenen Link-Tag in docuML.
Wenn Sie auf andere Abschnitte verweisen möchten, müssen Sie
ein konventionelles Anker-Tag verwenden und auf die entsprechende HTML-Datei
(da aus der XML-Datei eine HTML-Datei generiert wird) mit dem Ankernamen des
Abschnitts verweisen.
<!-- In der Datei diesedatei.xml -->
<s name="Abschnittsname" a="Ankername" >
<a href="diesedatei.html#Ankername">Dieser Link</a> verweist auf sich selbst.
</s>
Tabellen in docuML
Tabellen können Sie natürlich als XHTML-Tabellen mit <table>, <tr> und
<td> definieren, jedoch ist oft eine Anforderung, dass das Aussehen von
Tabellen in einem Dokument zentral geändert werden soll. Dafür ist die
Verwendung von dmltable vorgesehen, die zusammen mit dmlrow und dmlcol eine
Tabelle mit leicht grauem Hintergrund darstellt. Allerdings soll noch keinem
der Kopf abgesägt worden sein, weil er dieses Aussehen in documl.xsl geändert hätte...
<dmltable>
<dmlrow> <dmlcol>Hallo</dmlcol> <dmlcol>Welt</dmlcol> </dmlrow>
<dmlrow> <dmlcol colspan="2">Fließtext</dmlcol> </dmlrow>
</dmltable>
So wie dmlrow rowspan akzeptiert, funktioniert auch colspan bei dmlcol.
Neue Artikel anlegen
Um neue Artikel anzulegen, erstellen Sie bitte eine neue XML-Datei (mit einer neuen,
einmaligen ID) und
verlinken diese im
files-Bereich der Projektdatei.
Gegebenenfalls sollten Sie sie auch in Ihrem
Script
erwähnen.
Diese neue Datei sollte mindestens
ein Grundgerüst
beinhalten, ein
erweitertes Grundgerüst ist empfehlenswert.
usegroup
Was ist docuML?
