[PATCH] Datacage ref doc: More structure. Explain text interpolation

[Wald Commits]

# HG changeset patch
# User Sascha L. Teichmann <teichmann at intevation.de>
# Date 1381748913 -7200
# Node ID 53d1dd4418676a0ebda48476b544be4bdc8b9ccb
# Parent  bcae19901bf0de0b55c8a6ca0280a0256141d99d
Datacage ref doc: More structure. Explain text interpolation.

diff -r bcae19901bf0 -r 53d1dd441867 artifacts/doc/datacage_ref_de.rst
--- a/artifacts/doc/datacage_ref_de.rst	Mon Oct 14 12:16:33 2013 +0200
+++ b/artifacts/doc/datacage_ref_de.rst	Mon Oct 14 13:08:33 2013 +0200
@@ -8,12 +8,46 @@
 Ü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
 ------------------
 
-``dc:element`` **TODO**
-
-``dc:attribute`` **TODO**
+Datensätze erzeugen
+~~~~~~~~~~~~~~~~~~~
 
 ``dc:context`` **TODO**
 
@@ -23,11 +57,24 @@
 
 ``dc:properties`` **TODO**
 
+``dc:virtual-column`` **TODO**
+
+Datensätze einschränken
+~~~~~~~~~~~~~~~~~~~~~~~
+
+``dc:filter`` **TODO**
+
+``dc:group`` **TODO**
+
+Datensätze auffalten
+~~~~~~~~~~~~~~~~~~~~
+
 ``dc:for-each`` **TODO**
 
 ``dc:iterate`` **TODO**
 
-``dc:virtual-column`` **TODO**
+Makros
+~~~~~~
 
 ``dc:macro`` **TODO**
 
@@ -35,12 +82,39 @@
 
 ``dc:call-macro`` **TODO**
 
+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`` **TODO**
 
-``dc:filter`` **TODO**
-
-``dc:group`` **TODO**
-
 ``dc:message`` **TODO**
 
 ``dc:variable`` **TODO**
@@ -85,11 +159,6 @@
 ``<dc:choose>`` ist in Symmetrie zu ``<xsl:choose>`` von XSLT entworfen worden.
 
 
-Variablen
----------
-
-Textersatz
-----------
 
 Datenkorb-Funktionen
 --------------------