[PATCH] Dataage ref doc: Explain dc:context, dc:comment

[Wald Commits]

# HG changeset patch
# User Sascha L. Teichmann <teichmann at intevation.de>
# Date 1381751094 -7200
# Node ID 8498fdd71a1e5d9df612a11c1458e90d452bdc9b
# Parent  53d1dd4418676a0ebda48476b544be4bdc8b9ccb
Dataage ref doc: Explain dc:context, dc:comment

diff -r 53d1dd441867 -r 8498fdd71a1e artifacts/doc/datacage_ref_de.rst
--- a/artifacts/doc/datacage_ref_de.rst	Mon Oct 14 13:08:33 2013 +0200
+++ b/artifacts/doc/datacage_ref_de.rst	Mon Oct 14 13:44:54 2013 +0200
@@ -49,9 +49,51 @@
 Datensätze erzeugen
 ~~~~~~~~~~~~~~~~~~~
 
-``dc:context`` **TODO**
+``dc:context`` Aufspannen eines Gültigkeitsbereiches eines Datenbankdatensatz
+.............................................................................
 
-``dc:statement`` **TODO**
+.. 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**
 
@@ -110,10 +152,18 @@
 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:comment`` **TODO**
 
 ``dc:message`` **TODO**