Documnt place

layers/place/place.yaml

@@ -3,16 +3,25 @@ layer:
   description: |
       The place layer consists out of [countries](http://wiki.openstreetmap.org/wiki/Tag:place%3Dcountry),
       [states](http://wiki.openstreetmap.org/wiki/Tag:place%3Dstate) and [cities](http://wiki.openstreetmap.org/wiki/Key:place).
-      For countries, states and places at low zoom levels (`z0` to `z7`) the
-      [Populated Places](http://www.naturalearthdata.com/downloads/10m-cultural-vectors/10m-populated-places/) dataset from NaturalEarth is merged
-      with OSM data to only show the most relevant places for the given zoom level. All features derived from NaturalEarth have a `scalerank` field.
-      States and countries additionally contain `postal` and `abbreviation` fields for styles that want to fit a lot of data with small labels on the map. 
-      The `place` layer only contains more important states (or similar entities) from the US, Russia, China and Brazil.
-
+      Apart from the roads this is also one of the more important layers to create a beautiful map.
+      We suggest you use different font styles and sizes to create a text hierarchy.
+  fields:
+    name: The OSM [`name`](http://wiki.openstreetmap.org/wiki/Key:name) value of the POI.
+    name_en: The english `name:en` value if available.
+    class: |
+        Distinguish between `country`, `state` and other city classes like
+        `city`, `town`, `village`, `hamlet`, `suburb`, `neighbourhood` or `isolated_dwelling`.
+        Use this to separately style the different places according to their importance (usually country and state different
+        than cities).
+    rank: |
+        Countries, states and the most important cities all have a `rank` field ranging from `1` to `6` which
+        marks the importance of the feature. Less important places do not have a `rank`.
+        Use this to build a text hierarchy. The rank value originates from Natural Earth data and is either the
+        original `scalerank` for cities or the original `labelrank` for countries and states.
   buffer_size: 128
   datasource:
     geometry_field: geometry
-    query: (SELECT geometry, name, name_en, class, abbrev scalerank FROM layer_place(!bbox!, z(!scale_denominator!), !pixel_width!)) AS t
+    query: (SELECT geometry, name, name_en, class, rank FROM layer_place(!bbox!, z(!scale_denominator!), !pixel_width!)) AS t
 schema:
   - ./types.sql
   - ./city.sql