New docs

aeroway.md

@@ -25,3 +25,28 @@ Possible values:
 ![](aeroway.png)
 
 
+#aeroway
+Aeroway polygons based of OpenStreetMap [aeroways](http://wiki.openstreetmap.org/wiki/Aeroways).
+Airport buildings are contained in the **building** layer but all
+other airport related polygons can be found in the **aeroway** layer.## Fields
+
+### class
+
+The original value of the [`aeroway`](http://wiki.openstreetmap.org/wiki/Key:aeroway) tag.
+
+Possible values:
+
+- `aerodrome`
+- `heliport`
+- `runway`
+- `helipad`
+- `taxiway`
+- `apron`
+
+
+
+
+## Mapping Diagram
+![](media/mapping_aeroway.png)
+## ETL Diagram
+![](media/etl_aeroway.png)

boundary.md

@@ -31,3 +31,34 @@ Possible values:
 ![](boundary.png)
 
 
+#boundary
+Contains administrative boundaries as linestrings (no maritime boundaries yet) as linestrings.
+Until z7 [Natural Earth data](http://www.naturalearthdata.com/downloads/10m-cultural-vectors/10m-admin-0-countries/)
+is used after which OSM boundaries ([`boundary=administrative`](http://wiki.openstreetmap.org/wiki/Tag:boundary%3Dadministrative)) are present from z8 to z14.
+OSM data contains all [`admin_level`](http://wiki.openstreetmap.org/wiki/Tag:boundary%3Dadministrative#admin_level)
+but for most styles it makes sense to just style `admin_level=2` and `admin_level=4`.## Fields
+
+### admin_level
+
+OSM [admin_level](http://wiki.openstreetmap.org/wiki/Tag:boundary%3Dadministrative#admin_level)
+indicating the level of importance of this boundary.
+The `admin_level` corresponds to the lowest `admin_level`
+the line participates in.
+At low zoom levels the Natural Earth boundaries are mapped to the equivalent admin levels.
+
+### disputed
+
+Mark with `1` if the boundary is disputed.
+
+Possible values:
+
+- `0`
+- `1`
+
+
+
+
+## Mapping Diagram
+![](media/mapping_boundary.png)
+## ETL Diagram
+![](media/etl_boundary.png)

building.md

@@ -19,3 +19,22 @@ An approximated height from levels and height of the building or building:part a
 ![](building.png)
 
 
+#building
+All [OSM Buildings](http://wiki.openstreetmap.org/wiki/Buildings). All building tags are imported ([`building=*`](http://wiki.openstreetmap.org/wiki/Key:building)). The buildings are not yet ready for 3D rendering support and any help to improve
+this is welcomed.## Fields
+
+### render_min_height
+
+An approximated height from levels and height of the bottom of the building or building:part after the method of Paul Norman in [OSM Clear](https://github.com/ClearTables/osm-clear). For future 3D rendering of buildings.
+
+### render_height
+
+An approximated height from levels and height of the building or building:part after the method of Paul Norman in [OSM Clear](https://github.com/ClearTables/osm-clear). For future 3D rendering of buildings.
+
+
+
+
+## Mapping Diagram
+![](media/mapping_building.png)
+## ETL Diagram
+![](media/etl_building.png)

generate_jekyll_doc.sh

@@ -1,51 +0,0 @@
-#!/bin/bash
-set -o errexit
-set -o nounset
-
-function generate_diagrams() {
-    local layer_name="$1"
-    local tileset="./layers/$layer_name/$layer_name.yaml"
-    local target_dir="./layerdocs"
-    local target="./layerdocs/$layer_name.developer.md"
-
-    echo '---' > $target 
-    echo 'layout: layer_developer' >> $target 
-    echo "title: $layer_name" >> $target 
-    echo '---' >> $target 
-
-    generate-etlgraph "$tileset" "$target_dir"
-}
-
-function generate_user_doc() {
-    local layer_name="$1"
-    local tileset="./layers/$layer_name/$layer_name.yaml"
-    local target="./layerdocs/$layer_name.md"
-
-    echo '---' > $target 
-    echo 'layout: layer_user' >> $target 
-    echo "title: $layer_name" >> $target 
-    echo '---' >> $target 
-
-    generate-doc "$tileset" >> $target
-}
-
-
-function generate_docs() {
-    mkdir -p ./layerdocs
-    generate_user_doc "aeroway"
-    generate_user_doc "building"
-    generate_user_doc "housenumber"
-    generate_user_doc "landuse"
-    generate_user_doc "place"
-    generate_user_doc "transportation"
-    generate_user_doc "water"
-    generate_user_doc "waterway"
-    generate_user_doc "boundary"
-    generate_user_doc "landcover"
-    generate_user_doc "park"
-    generate_user_doc "poi"
-    generate_user_doc "transportation_name"
-    generate_user_doc "water_name"
-}
-
-generate_docs

housenumber.md

@@ -12,3 +12,18 @@ Value of the [`addr:housenumber`](http://wiki.openstreetmap.org/wiki/Key:addr) t
 
 
 
+#housenumber
+Everything in OpenStreetMap which contains a `addr:housenumber` tag useful for labelling housenumbers on a map.
+This adds significant size to *z14*. For buildings the centroid of the building is used as housenumber.## Fields
+
+### housenumber
+
+Value of the [`addr:housenumber`](http://wiki.openstreetmap.org/wiki/Key:addr) tag.
+
+
+
+
+## Mapping Diagram
+![](media/mapping_housenumber.png)
+## ETL Diagram
+![](media/etl_housenumber.png)

landcover.md

@@ -60,3 +60,63 @@ Possible values:
 ![](landcover.png)
 
 
+#landcover
+Landcover is used to describe the physical material at the surface of the earth. At lower zoom levels this is
+from Natural Earth data for glaciers and ice shelves and at higher zoom levels the [landcover is [implied by OSM tags](http://wiki.openstreetmap.org/wiki/Landcover). The most common use case for this layer
+  is to style wood (`class=wood`) and grass (`class=`grass`) areas.## Fields
+
+### class
+
+Use the **class** to assign natural colors for **landcover**.
+
+Possible values:
+
+- `farmland`
+- `ice`
+- `wood`
+- `grass`
+- `wetland`
+
+### subclass
+
+Use **subclass** to do more precise styling.
+Original value of either the
+[`natural`](http://wiki.openstreetmap.org/wiki/Key:natural),
+[`landuse`](http://wiki.openstreetmap.org/wiki/Key:landuse),
+,[`leisure`](http://wiki.openstreetmap.org/wiki/Key:leisure),
+or [`wetland`](http://wiki.openstreetmap.org/wiki/Key:wetland) tag.
+
+Possible values:
+
+- `allotments`
+- `farm`
+- `farmland`
+- `orchard`
+- `plant_nursery`
+- `vineyard`
+- `grass`
+- `grassland`
+- `meadow`
+- `forest`
+- `village_green`
+- `recreation_ground`
+- `park`
+- `wetland`
+- `grassland`
+- `bog`
+- `swamp`
+- `wet_meadow`
+- `marsh`
+- `reedbed`
+- `saltern`
+- `tidalflat`
+- `saltmarsh`
+- `mangrove`
+
+
+
+
+## Mapping Diagram
+![](media/mapping_landcover.png)
+## ETL Diagram
+![](media/etl_landcover.png)

landuse.md

@@ -36,3 +36,39 @@ Possible values:
 ![](landuse.png)
 
 
+#landuse
+Landuse is used to describe use of land by humans.At lower zoom levels this is
+from Natural Earth data for residential (urban) areas and at higher zoom levels mostly OSM `landuse` tags.## Fields
+
+### class
+
+Use the **class** to assign special colors to areas.
+Original value of either the
+[`amenity`](http://wiki.openstreetmap.org/wiki/Key:amenity),
+[`landuse`](http://wiki.openstreetmap.org/wiki/Key:landuse),
+or [`leisure`](http://wiki.openstreetmap.org/wiki/Key:leisure) tag.
+
+Possible values:
+
+- `school`
+- `university`
+- `kindergarten`
+- `college`
+- `library`
+- `hospital`
+- `railway`
+- `cemetery`
+- `military`
+- `residential`
+- `commercial`
+- `industrial`
+- `retail`
+- `stadium`
+
+
+
+
+## Mapping Diagram
+![](media/mapping_landuse.png)
+## ETL Diagram
+![](media/etl_landuse.png)

park.md

@@ -19,3 +19,22 @@ Possible values:
 ![](park.png)
 
 
+#park
+The park layer contains parks from OpenStreetMap tagged with either [`boundary=national_park`](http://wiki.openstreetmap.org/wiki/Tag:boundary%3Dnational_park) or [`leisure=nature_reserve`](http://wiki.openstreetmap.org/wiki/Tag:leisure%3Dnature_reserve).## Fields
+
+### class
+
+Use the **class** to differentiate between different parks.
+
+Possible values:
+
+- `national_park`
+- `nature_reserve`
+
+
+
+
+## Mapping Diagram
+![](media/mapping_park.png)
+## ETL Diagram
+![](media/etl_park.png)

place.md

@@ -69,3 +69,72 @@ The OSM [`name`](http://wiki.openstreetmap.org/wiki/Key:name) value of the POI.
 ![](place.png)
 
 
+#place
+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).
+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_en
+
+The English `name:en` value or local `name` if not available.
+
+### capital
+
+The **capital** field marks the
+[`admin_level`](http://wiki.openstreetmap.org/wiki/Tag:boundary%3Dadministrative#admin_level)
+of the boundary the place is a capital of.
+
+Possible values:
+
+- `2`
+- `4`
+
+### class
+
+description: |
+    Original value of the
+    [`place`](http://wiki.openstreetmap.org/wiki/Key:place) tag.
+    Distinguish between continents, countries, states and
+    places like settlements or smaller entities.
+    Use **class** to separately style the different places and build
+    a text hierarchy according to their importance.
+values:
+- continent
+- country
+- state
+- city
+- town
+- village
+- hamlet
+- suburb
+- neighbourhood
+- isolated_dwelling
+
+### rank
+
+Countries, states and the most important cities all have a
+**rank** to boost their importance on the map.
+The **rank** field for counries and states ranges from
+`1` to `6` while the **rank** field for cities ranges from
+`1` to `10` for the most important cities
+and continues from `10` serially based on the
+local importance of the city (derived from population and city class).
+You can use the **rank** to limit density of labels or improve
+the text hierarchy.
+The rank value is a combination of the Natural Earth
+`scalerank`, `labelrank` and `datarank` values for countries
+and states and for cities consists out of a shifted
+Natural Earth `scalerank` combined with a local rank
+within a grid for cities that do not have a Natural Earth `scalerank`.
+### name
+
+The OSM [`name`](http://wiki.openstreetmap.org/wiki/Key:name) value of the POI.
+
+
+
+
+## Mapping Diagram
+![](media/mapping_place.png)
+## ETL Diagram
+![](media/etl_place.png)

poi.md

@@ -44,3 +44,47 @@ tag.  Use this to do more precise styling.
 ![](poi.png)
 
 
+#poi
+[Points of interests](http://wiki.openstreetmap.org/wiki/Points_of_interest) containing
+a of a variety of OpenStreetMap tags. Mostly contains amenities, sport, shop and tourist POIs.## Fields
+
+### class
+
+More general classes of POIs. If there is no more general `class` for the `subclass`
+this field will contain the same value as `subclass`.
+But for example for schools you only need to style the class `school` to filter the subclasses `school`
+and `kindergarten`. Or use the class `shop` to style all shops.
+
+### name_en
+
+The english `name:en` value if available.
+
+### name
+
+The OSM [`name`](http://wiki.openstreetmap.org/wiki/Key:name) value of the POI.
+
+### rank
+
+The POIs are ranked ascending according to their importance within a grid. The `rank` value shows the
+local relative importance of a POI within it's cell in the grid. This can be used to reduce label density at z14.
+Since all POIs already need to be contained at `z14` you can use `less than rank=10` epxression to limit
+POIs. At some point like z17 you can show all POIs.
+
+### subclass
+
+Original value of either the
+[`amenity`](http://wiki.openstreetmap.org/wiki/Key:amenity),
+[`leisure`](http://wiki.openstreetmap.org/wiki/Key:leisure),
+[`landuse`](http://wiki.openstreetmap.org/wiki/Key:landuse),
+[`sport`](http://wiki.openstreetmap.org/wiki/Key:sport),
+[`tourism`](http://wiki.openstreetmap.org/wiki/Key:tourism)
+or [`shop`](http://wiki.openstreetmap.org/wiki/Key:shop)
+tag.  Use this to do more precise styling.
+
+
+
+
+## Mapping Diagram
+![](media/mapping_poi.png)
+## ETL Diagram
+![](media/etl_poi.png)

transportation.md

@@ -83,3 +83,86 @@ Possible values:
 ![](transportation.png)
 
 
+#transportation
+**transportation** contains roads and railways.
+This layer is directly derived from the OSM road hierarchy.
+Only at zoom level 4 to 6 some major highways from Natural Earth
+are used.
+It contains all roads from motorways to primary, secondary and
+tertiary roads to residential roads and
+foot paths. Styling the roads is the most essential part of the map.
+The `transportation` layer also contains polygons for things like plazas.## Fields
+
+### brunnel
+
+Mark whether way is a tunnel or bridge.
+
+Possible values:
+
+- `bridge`
+- `tunnel`
+- `ford`
+
+### ramp
+
+Mark with `1` whether way is a ramp (link or steps)
+or not with `0`.
+
+Possible values:
+
+- `0`
+- `1`
+
+### class
+
+Distinguish between more and less important roads or railways.
+Class is derived from the value of the
+[`highway`](http://wiki.openstreetmap.org/wiki/Key:highway) or
+[`railway`](http://wiki.openstreetmap.org/wiki/Key:railway) tag.
+
+Possible values:
+
+- `motorway`
+- `trunk`
+- `primary`
+- `secondary`
+- `tertiary`
+- `minor`
+- `service`
+- `track`
+- `path`
+- `raceway`
+- `rail`
+- `transit`
+
+### service
+
+Original value of the [`service`](http://wiki.openstreetmap.org/wiki/Key:service) tag.
+
+Possible values:
+
+- `spur`
+- `yard`
+- `siding`
+- `crossover`
+- `driveway`
+- `alley`
+- `parking_aisle`
+
+### oneway
+
+Mark with `1` whether way is a oneway (in the direction of the way)
+or not with `0`.
+
+Possible values:
+
+- `0`
+- `1`
+
+
+
+
+## Mapping Diagram
+![](media/mapping_transportation.png)
+## ETL Diagram
+![](media/etl_transportation.png)

transportation_name.md

@@ -45,3 +45,51 @@ The OSM [`name`](http://wiki.openstreetmap.org/wiki/Highways#Names_and_reference
 
 
 
+#transportation_name
+This is the layer for labelling the highways. Only highways that are named `name=*` and are long enough
+to place text upon appear. The OSM roads are stitched together if they contain the same name
+to have better label placement than having many small linestrings.
+For motorways you should use the `ref` field to label them while for other roads you should use `name`.## Fields
+
+### ref
+
+The OSM [`ref`](http://wiki.openstreetmap.org/wiki/Key:ref) tag of the motorway or road.
+
+### ref_length
+
+Length of the `ref` field. Useful for having a shield icon as background for labeling motorways.
+
+### class
+
+Distinguish between more and less important roads.
+
+Possible values:
+
+- `motorway`
+- `trunk`
+- `primary`
+- `secondary`
+- `tertiary`
+- `minor`
+- `service`
+- `track`
+- `path`
+- `raceway`
+- `rail`
+- `transit`
+
+### network
+
+The OSM [`network`](http://wiki.openstreetmap.org/wiki/Key:network) tag of the road.
+
+### name
+
+The OSM [`name`](http://wiki.openstreetmap.org/wiki/Highways#Names_and_references) value of the highway.
+
+
+
+
+## Mapping Diagram
+![](media/mapping_transportation_name.png)
+## ETL Diagram
+![](media/etl_transportation_name.png)

water.md

@@ -19,3 +19,22 @@ Either `ocean`, `lake` or `river`.
 ![](water.png)
 
 
+#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 Diagram
+![](media/mapping_water.png)
+## ETL Diagram
+![](media/etl_water.png)

water_name.md

@@ -24,3 +24,27 @@ At the moment only `lake` since no ocean parts are labelled. *Reserved for futur
 ![](water_name.png)
 
 
+#water_name
+Lake center lines for labelling lake bodies.
+This is based of the [osm-lakelines](https://github.com/lukasmartinelli/osm-lakelines) project
+which derives nice centerlines from OSM water bodies. Only the most important lakes contain labels.## Fields
+
+### name_en
+
+The english `name:en` value if available.
+
+### name
+
+The OSM [`name`](http://wiki.openstreetmap.org/wiki/Key:name) value of the water body.
+
+### class
+
+At the moment only `lake` since no ocean parts are labelled. *Reserved for future use*.
+
+
+
+
+## Mapping Diagram
+![](media/mapping_water_name.png)
+## ETL Diagram
+![](media/etl_water_name.png)

waterway.md

@@ -27,3 +27,30 @@ Can be one of [`stream`](http://wiki.openstreetmap.org/wiki/Tag:waterway%3Dstrea
 ![](waterway.png)
 
 
+#waterway
+Rivers based of OpenStreetMap [waterways](http://wiki.openstreetmap.org/wiki/Waterways) for *z9* to *z14*
+and Natural Earth rivers and lake centerlines from *z3* to *z8*.
+Linestrings without a name or which are too short are filtered
+out at low zoom levels. Waterways do no not have a `subclass` field.## Fields
+
+### name
+
+The OSM [`name`](http://wiki.openstreetmap.org/wiki/Key:name) value of the waterway.
+The `name` field is empty for NaturalEarth data until **z9** when OSM data is used.
+
+### class
+
+The original value of the [`waterway`](http://wiki.openstreetmap.org/wiki/Key:waterway) tag.
+Can be one of [`stream`](http://wiki.openstreetmap.org/wiki/Tag:waterway%3Dstream),
+[`river`](http://wiki.openstreetmap.org/wiki/Tag:waterway%3Driver),
+[`canal`](http://wiki.openstreetmap.org/wiki/Tag:waterway%3Dcanal),
+[`drain`](http://wiki.openstreetmap.org/wiki/Tag:waterway%3Ddrain),
+[`ditch`](http://wiki.openstreetmap.org/wiki/Tag:waterway%3Dditch)`.
+
+
+
+
+## Mapping Diagram
+![](media/mapping_waterway.png)
+## ETL Diagram
+![](media/etl_waterway.png)