--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/artifacts/doc/datacage_ref_de.rst	Tue Oct 15 18:41:55 2013 +0200
@@ -0,0 +1,530 @@
+=========
+Datenkorb
+=========
+
+
+.. contents:: Inhalt
+
+Übersicht
+---------
+
+Daten
+-----
+Im Datenkorb stehen zwei Arten von Daten zur Auswertung zur Verfügung.
+
+``Datensätze``
+~~~~~~~~~~~~~~
+Datensätze sind Tabellen mit benannten Spalten. Sie werden von Datenquellen
+erzeugt und in einem Stapel verwaltet. Die konkreten Werte stehen erst durch
+Auffaltung als Variablen zur Verfügung.
+
+
+``Variablen``
+~~~~~~~~~~~~~
+Variablen sind die Werte, die aktuell zur Auswertung zur Verfügung stehen. Sie haben
+einen Namen und einen Typ (String, Zahl, durch Datenquelle bestimmt).
+
+Textersatz
+----------
+Um die Wertebelegungen in das Ausgabedokument schreiben zu kann an entsprechenden
+Stellen eine String-Interpolation durchgeführt werden.
+Hier finden zwei Arten von Textersatz ihren Einsatz.
+
+``${}-Ersetzungen``
+~~~~~~~~~~~~~~~~~~~
+Die ältere Variante. Innerhalb von Strings werden hier nur Variablen aufgelöst.
+Beispiel: "**Hallo, ${planet}!**" wird bei planet = 'Welt' zu "**Hallo, Welt!**".
+
+``{$}-Ersetzungen``
+~~~~~~~~~~~~~~~~~~~
+Die neuere Variante, allerdings noch nicht komplett an allen Stellen einsatzfähig.
+Innerhalb der geschweiften Klammern können beliebige XPath-Ausdrück stehen, die
+zu Strings evaluiert werden. Dies orientiert sich an den String-Auswertungen in XSLT.
+"**{ concat($greet, ', ', $planet, '!') }**" wird bei gesetzten Variablen greet = Hallo
+und planet = "Welt" zu **Hallo, Welt!** ausgewertet.
+
+Datenkorb-Elemente
+------------------
+
+Datensätze erzeugen
+~~~~~~~~~~~~~~~~~~~
+
+``dc:context`` Aufspannen eines Gültigkeitsbereiches eines Datenbankdatensatz
+.............................................................................
+
+.. code:: xml
+
+    <dc:context connection="Verbindung">
+      ...
+    </dc:element>
+
+Spannt einen Gültigkeitsbereich für einen Datensatz auf, der aus der Datenbank
+kommt. Die adressierte Datenbank wird über das optionale Attribut 'connection'
+bestimmt. Zur Zeit sind drei Datenbanken angebunden:
+
+- **user**: Die Index-Datenbank des Artefakt-Servers. Hierüber stehen Meta-Informationen
+  zu alten Berechnungen zur Verfügung.
+
+- **system**: Die FLYS-Datenbank mit den hydrologischen, morphologische und geodätischen
+  Daten.
+
+- **seddb**: Die Sediment-Datenbank.
+
+In einem `<dc:context>`-Element wird zwingend ein `<dc:statement>`-Element erwartet,
+um einen Datensatz aus der Datenbank zu holen. Dieser Datensatz steht dann innerhalb des
+`<dc:context>`-Elementes ein oder mehrfach zur Verfügung. Innerhalb eines
+`<dc:context>`-Elementes können weitere `<dc:context>`-Elemente eingeschachtelt werden.
+Ist kein 'connection'-Attribut vorhanden, wird die Datenbank-Verbindung des umgebenen
+Kontextes weiterbenutzt. Initial wird je nach Aufrufart der Datenkorbs entweder
+der **user** oder **system**-Kontext angenommen. Dies richtet sich danach, ob in
+der Aufrufumgebung eine Artefakt gesetzt wird oder nicht. Im ersten Fall wird
+angenommen, dass es sich um einen Ladevorgang für zusätzliche Daten handelt, die
+auch alte Berechnungen mit einschliesst.
+
+
+``dc:statement`` Holen eines Datensatzes aus einer Datenbank
+............................................................
+
+.. code:: xml
+
+    <dc:statement>
+      SQL-Select-Statement.
+    </dc:element>
+
+Mittels eines SQL-Select-Statements werden in einem `<dc:context>`-Elementes aus
+der dort definierten Datenbank geholt. Die Spaltennamen der Projektion des SQL-Statements
+werden übernommen und später beim Auffalten des Datensatzes benutzt.
+
+``dc:container-context`` **TODO**
+
+``dc:properties`` **TODO**
+
+``dc:virtual-column`` Virtuelle Spalten definieren
+..................................................
+
+.. code:: xml
+
+    <dc:virtual-column name="Name" type="Type" expr="XPath-Ausdruck">
+      ...
+    </dc:virtual-column>
+
+Definiert eine neue, virtuelle Spalte namens Name für den aktuellen Datensatz.
+Der Typ wird optional durch Typ festgelegt; ohne Angabe wird der Typ String angenommen.
+Die Wertebelegung ergibt sich aus der zeilenweisen Auswertung des XPath-Ausdrucks.
+
+Dies sei an folgendem Beispiel illustriert:
+
+ +----+
+ +Zahl+
+ +====+
+ +   1+
+ +----+
+ +   2+
+ +----+
+ +   3+
+ +----+
+
+.. code:: xml
+
+    <dc:virtual-column name="Quadrat" type="number" expr="$Zahl * $Zahl">
+      ...
+    </dc:virtual-column>
+
+Erzeugt einen neuen Datensatz folgender Struktur:
+
+ +----+-------+
+ +Zahl+Quadrat+
+ +====+=======+
+ +   1+      1+
+ +----+-------+
+ +   2+      4+
+ +----+-------+
+ +   3+      9+
+ +----+-------+
+
+Innerhalb eines `virtual-column`-Elementes kann der Datensatz mittel `dc:for-each` wie
+gewohnt realisiert werden. Wird das `dc:virtual-column`-Element verlassen, gilt wieder
+der vormalige Datensatz ohne die zusätzlich Spalte.
+
+Datensätze einschränken
+~~~~~~~~~~~~~~~~~~~~~~~
+
+``dc:filter`` Selektieren einzelner Zeilen aus dem aktuellen Datensatz
+......................................................................
+
+.. code:: xml
+
+    <dc:filter expr="XPath-Ausdruck">
+      ...
+    </dc:filter>
+
+Evaluiert pro Zeile des aktuellen Datensatzes den XPath-Ausdruck 'expr' und erzeugt
+einen neuen Datensatz, der nur die Zeilen des Originaldatensatzes enthält für den
+die Auswertung logisch wahr ergab. Im XPath-Ausdruck stehen die aufgefalteten Werte
+der jeweiligen Zeile zur Verfügung.
+
+Folgends Beispiel soll dies verdeutlichen:
+
+ +----+
+ +Zahl+
+ +====+
+ +   1+
+ +----+
+ +   2+
+ +----+
+ +   3+
+ +----+
+ +   4+
+ +----+
+
+Zahlen erhalten, die einen Wert kleiner drei haben.
+
+.. code:: xml
+
+    <dc:filter expr="$Zahl &lt; 3">
+      ...
+    <dc:filter>
+
+Dies erzeugt folgenden neuen Datensatz:
+
+ +----+
+ +Zahl+
+ +====+
+ +   1+
+ +----+
+ +   2+
+ +----+
+
+Innerhalb des `dc:filter`-Elementes kann der neue Datensatz wie gewohnt mit `dc:for-each`
+realisiert werden. Nach Verlassen des `dc:filter`-Elementes ist wieder der vormalige
+Datensatz aktuell.
+
+``dc:group`` Datensätzen in Gruppen ordnen
+..........................................
+
+.. code:: xml
+
+    <dc:group expr="XPath-Ausdruck">
+      ...
+    </dc:group>
+
+Pro Zeile der Originaldatensatzes wird der XPath-Ausdruck 'expr' ausgewertet.
+Wie bei `dc:filter` stehen hier die aufgefalteten Werte der einzelnen Spalten zur
+Verfügung. Das Resultat der XPath-Auswertung wird als Schlüssel für zu erzeugende
+Gruppen benutzt, denen dann die Zeilen zugeordnet werden.
+Nachdem alle Zeilen ihren entsprechenden Gruppen zugeordnet wurden, wir der
+Inhalt des `dc:group`-Elements für jede Gruppe durchlaufen. Innerhalb des
+`dc:group`-Elementes steht der jeweilige Schlüssel der aktuellen Gruppe über
+die Funktion `dc:group-key()` zur Auswertung zu Verfügung. Innerhalb der
+jeweiligen Gruppen kann mittel `dc:for-each` der jeweilige Unterdatensatz
+realisiert werden.
+
+Zur Verdeutlichung folgendes Beispiel:
+
+ +-------+-----------+
+ +Marke  +Bezeichnung+
+ +=======+===========+
+ +Ferrari+Testarossa +
+ +-------+-----------+
+ +Volvo  +V40        +
+ +-------+-----------+
+ +Volvo  +780        +
+ +-------+-----------+
+ +Ferrari+F40        +
+ +-------+-----------+
+ +VW     +Käfer      +
+ +-------+-----------+
+
+.. code:: xml
+
+    <marken>
+      <dc:group expr="$Marke">
+        <marke name="{dc:group-key()}">
+           <dc:for-each>
+              <bezeichnung name="$Bezeichnung"/>
+           </dc:for-each>
+        </marke>
+      </dc:group>
+    </marken>
+
+Dies führt zu folgender Ausgabe:
+
+.. code:: xml
+
+    <marken>
+      <marke name="Ferrari">
+        <bezeichnung name="F40"/>
+        <bezeichnung name="Testarossa"/>
+      </marke>
+      <marke name="Volvo">
+        <bezeichnung name="V40"/>
+        <bezeichnung name="780"/>
+      </marke>
+      <marke name="VW">
+        <bezeichnung name="Käfer"/>
+      </marke>
+    </marken>
+
+Datensätze auffalten
+~~~~~~~~~~~~~~~~~~~~
+
+``dc:for-each`` Realisieren eines Datensatzes
+.............................................
+
+.. code:: xml
+
+    <dc:for-each>
+      ...
+    <dc:for-each>
+
+Erzeugt nacheinander alle zeilenweisen Realisationen des aktuellen Datensatzes. Die
+einzelnen Spaltenwerte sind dann über Variablen erreichbar, die nach den Spaltenbezeichnern
+des Datenstzes benannt sind.
+
+Folgendes Beispiel soll den Sachverhalt illustieren:
+
+ +----+
+ +Zahl+
+ +====+
+ +   1+
+ +----+
+ +   2+
+ +----+
+ +   3+
+ +----+
+
+.. code:: xml
+
+    <zahlen>
+      <dc:for-each>
+        <zahl wert="$Zahl"/>
+      <dc:for-each>
+    </zahlen>
+
+Dies erzeugt folgende Ausgabe:
+
+.. code:: xml
+
+    <zahlen>
+        <zahl wert="1"/>
+        <zahl wert="2"/>
+        <zahl wert="3"/>
+    </zahlen>
+
+``dc:iterate`` **TODO**
+
+Bedingte Ausführung
+~~~~~~~~~~~~~~~~~~~
+
+``<dc:if>`` Einfaches Wenn-Dann ohne Sonst-Fall
+...............................................
+
+.. code:: xml
+
+    <dc:if test="XPath-Ausdruck">
+      ...
+    </dc:if>
+
+Der innere Teil wird nur dann betreten, wenn der XPath-Ausdruck zu
+logisch wahr evaluiert wird. Dieses Konstrukt kennt keinen alternativen
+Pfad, der betreten wird, falls der Ausdruck zu logisch falsch ausgewertet
+wird. Wird dies benötigt, muss man ``<dc:choose>`` benutzen.
+``<dc:if>`` ist in Symmetrie zu ``<xsl:if>`` von XSLT entworfen worden.
+
+``<dc:choose>`` Ketten von Wenn-Dann-Ausdrücken
+...............................................
+
+.. code:: xml
+    
+    <dc:choose>
+       <dc:when test="XPath-Ausdruck 1"> ... </dc:when>
+       <dc:when test="XPath-Ausdruck 2"> ... </dc:when>
+       ...
+       <dc:otherwise> ...  </dc:otherwise>
+    </dc:choose>
+
+Es werden der Reihe nach von oben nach unter die ``test``-XPath-Ausdrücke der ``dc:when``-Elemente ausgewertet.  Evaluiert ein Ausdruck zu logisch wahr, wird der innere Teil des entsprechenden ``<dc:when>``-Elements betreten. Die verbliebenen
+``<dc:when>``- und ``<dc:otherwise>``-Elemente werden dann ignoriert. Evaluiert
+keiner der ``test``-Ausdrücke zu wahr, wird der innere Teil des
+``<dc:otherwise>``-Elements betreten.
+``<dc:choose>`` ist in Symmetrie zu ``<xsl:choose>`` von XSLT entworfen worden.
+
+
+
+Makros
+~~~~~~
+Um innerhalb des Definitionsdokumentes Wiederholungen zu vermeiden, können sogenannte
+Makros definiert werden, die dann von anderer Stellen aus eingefügt werden können.
+
+``dc:macro`` Wiederverwendbare Teile definieren
+...............................................
+
+.. code:: xml
+
+    <dc:macro name="Name">
+      ...
+    </dc:macro>
+
+Definiert ein Makro namens Name. Nach der Definition ist dieses dann unter diesem
+Namen global innerhalb des Definitionsdokumentes bekannt. Makros können geschachtelt
+werden. Auch eingeschachtelte Makros sind global sichtbar. Die Makrodefinition und
+ihre eingeschalteten Elemente werden nicht in das Ausgabedokument übernommen.
+
+``dc:call-macro`` Makros aufrufen
+
+.. code:: xml
+
+    <dc:call-macro name="Name">
+
+Ruft ein Makro names Name auf. Dieses muss mit `dc:macro` definiert sein. Die Reihenfolge
+von Definition und Aufruf ist egal.
+
+``dc:macro-body`` Elemente an ein Makro übergeben
+.................................................
+
+.. code:: xml
+
+    <dc:macro name="Name">
+      ...
+      <dc:macro-body/>
+      ...
+    </dc:macro>
+
+Um an Makros weitere Bausteine als Argument übergeben zu können, ist es optional
+möglich innerhalb einer Makrodefinition ein Element `dc:macro-body` einzufügen.
+Dieses Element expandiert sich zum Inhalt des `dc:call-macro`-Aufrufs.
+
+.. code:: xml
+
+    <dc:call-macro name="Name">Inhalt von dc:macro-body</dc:call-macro>
+
+Zur Verdeutlichung ein konkretes Beispiel
+
+.. code:: xml
+
+    <dc:macro name="Greetings">
+      <Hallo>
+          <dc:macro-body/>
+      </Hallo>
+    </dc:macro>
+
+    <dc:call-macro name="Greetings">Welt</dc:call-macro>
+    <dc:call-macro name="Greetings">Mond</dc:call-macro>
+
+Dies produziert folgende Ausgabe
+
+.. code:: xml
+
+    <Hallo>Welt</Hallo>
+    <Hallo>Mond</Hallo>
+
+Das Haupteinsatzgebiet dieses Konstruktes ist die transparente Bereitstellung
+von Kontexten, die dann verschiedentlich ausgewertet werden sollen.
+
+Sonstige Elemente
+~~~~~~~~~~~~~~~~~
+
+``dc:element`` Hinzufügen neuer Elemente in der Ausgabe
+.......................................................
+
+.. code:: xml
+
+    <dc:element name="Name">
+      ...
+    </dc:element>
+
+Erzeugt ein Element namens Name. Für den Namen gelten die `${}-Ersetzungen`_.
+
+
+``dc:attribute`` Hinzufügen neuer Attribute zum umgebenden Ausgabeelement
+.........................................................................
+
+.. code:: xml
+
+    <dc:attribute name="Name" value="Wert"/>
+
+Fügt dem umgebenden Ausgabeelement ein weiteres Attribut namens Name mit dem
+Wert von Wert hinzu. Für Namen und Wert gelten die `${}-Ersetzungen`_.
+Der Einsatz dieses Konstrukts findet häufig im Zusammenhang mit dc:element
+seinen Einsatz, wenn es ein Ausgabeelement vollständig aus Variablenbelegungen
+erstellt werden soll.
+
+``dc:comment`` Kommentare im Beschreibungsdokument
+..................................................
+
+.. code:: xml
+
+    <dc:comment>
+      ...
+    </dc:comment>
+
+Ein Kommentar auf Ebene des Beschreibungsdokumentes, das keinerlei Ausgabe
+im Ausgabedokument erzeugt. Eingeschachtelte Elemente werden ebenfalls nicht ausgewertet.
+Im Gegensatz dazu werden die XML-typischen **<!-- Kommetare -->** in das Ausgabedokument übernommen!
+
+
+``dc:message`` Ausgabe auf die Diagnoseausgabe (Log)
+....................................................
+
+.. code:: xml
+
+    <dc:message>
+      Text für die Diagnose.
+    </dc:message>
+
+Gibt den Text innerhalb des Elementes aus Ausgabe im Log aus. Dies dient in erster Linie
+dem Nachvollziehen von Aufrufen innerhalb des Datenkorbdokumentes. Für den Text gelten
+die `{$}-Ersetzungen`_.
+
+``dc:variable`` Erzeugung einer kontext-lokalen Variablen
+.........................................................
+
+.. code:: xml
+
+    <dc:variable name="Name" type="Typ" expr="XPath-Ausdruck"/>
+
+Legt im aktuellen Kontext eine lokale Variable namens Name an. Diese hat den
+Typ Typ und entsteht durch Auswertung des XPath-Ausdruck expr. Der Typ
+ist optional. Wird dieser nicht gesetzt, wird das Ergebnis als String interpretiert.
+Alternativ können hier die Werte 'number' für Zahlen, 'bool' für Boolean-Werte
+benutzt werden. Für den Namen und den Typ gelten die `${}-Ersetzungen`_.
+Wird der aktuellen `dc:context` verlassen, ist diese Variable nicht mehr definiert.
+
+
+``dc:convert`` kontext-lokale Konvertierung von Variablen
+.........................................................
+
+.. code:: xml
+
+    <dc:convert name="Name" type="Typ"/>
+
+Konvertiert die Variable namens Name für die Gültigkeit des aktuellen Kontextes in
+einen anderen Typ. Für Name und Typ gelten die `${}-Ersetzungen`_. Für die
+Typen gilt das gleiche wie für die Typen von `dc:variable`.
+
+
+Datenkorb-Funktionen
+--------------------
+
+``dc:contains`` **TODO**
+
+``dc:fromValue`` **TODO**
+
+``dc:toValue`` **TODO**
+
+``dc:replace`` **TODO**
+
+``dc:replace-all`` **TODO**
+
+``dc:has-result`` **TODO**
+
+``dc:group-key`` **TODO**
+
+``dc:date-format`` **TODO**
+
+``dc:dump-variables`` **TODO**
+
+``dc:get`` **TODO**
+
+
+