Document water and remove obsolete mapping

layers/water/README.md

@@ -0,0 +1,18 @@
+# water
+
+Water polygons representing oceans and lakes. Covered watered areas are excluded (`covered=yes`).
+Until z6 all water originates from Natural Earth. To get a more correct display of the south pole you should also
+style the covering ice shelves over the water.
+Water from OpenStreetMap after z7 is split into many smaller polygons to improve rendering performance.
+This however can lead to less rendering options in clients since these boundaries show up. So you might not be
+able to use border styling for ocean water features.
+
+## Fields
+
+- **class**: Either `ocean`, `lake` or `river`.
+
+## Mapping
+
+![](mapping.png)
+
+

layers/water/mapping.yaml

@@ -52,25 +52,3 @@ tables:
       - drain
       - ditch
     type: polygon
-  water_linestring:
-    fields:
-    - name: osm_id
-      type: id
-    - name: geometry
-      type: geometry
-    - name: waterway
-      type: mapping_value
-    - key: name
-      name: name
-      type: string
-    - name: name_en
-      key: name:en
-      type: string
-    mapping:
-      waterway:
-      - stream
-      - river
-      - canal
-      - drain
-      - ditch
-    type: linestring

layers/water/water.yaml

@@ -1,7 +1,15 @@
 layer:
   id: "water"
   description: |
-      Water polygons and linestrings representing oceans, lakes.
+      Water polygons representing oceans and lakes. Covered watered areas are excluded (`covered=yes`).
+      Until z6 all water originates from Natural Earth. To get a more correct display of the south pole you should also
+      style the covering ice shelves over the water.
+      Water from OpenStreetMap after z7 is split into many smaller polygons to improve rendering performance.
+      This however can lead to less rendering options in clients since these boundaries show up. So you might not be
+      able to use border styling for ocean water features.
+  fields:
+    class: |
+        Either `ocean`, `lake` or `river`.
   buffer_size: 4
   datasource:
     query: (SELECT geom, class FROM layer_water(!bbox!, z(!scale_denominator!))) AS t