From 73967ccfd3c28c3d9aea49ce3425057acacb0c72 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ladislav=20Hork=C3=BD?= <ladislav.horky@citationtech.net>
Date: Tue, 31 Oct 2017 13:56:08 +0100
Subject: [PATCH] clarifying and expanding docs/resources.md

---
 docs/resources.md | 36 ++++++++++++++++++++++++------------
 1 file changed, 24 insertions(+), 12 deletions(-)

diff --git a/docs/resources.md b/docs/resources.md
index 390b01b..8f3eeb2 100644
--- a/docs/resources.md
+++ b/docs/resources.md
@@ -2,12 +2,28 @@
 
 This file is the authoritative mapproxy resource documentation. Please, keep it in sync with the actual implementation.
 
+# Resource definition file
+
+Most common way to define resources for mapproxy is to provide JSON resource definition file and point mapproxy to it by specifying its path in `resource-backend.path` configuration parameter.
+
+The resource definition file can contain resource definitions or include
+subsequent definition files:
+```
+[
+    Resource,    // see below
+    Resource,
+    ...
+    { "include": String }, // path to other definition file to include.
+    ...                    // may be relative to current directory
+]
+```
+
 # Supported resource types/drivers
 
 Mapproxy supports following resource types:
  * tms: *tile map service* (bound layer)
  * surface: surfaces (i.e. tileset generator)
- * geodata: vector free layers
+ * geodata: vector free layers, monolithic or tiled
 
 Mapproxy provides multiple drivers (*generators*) for each resource type.
 
@@ -46,10 +62,10 @@ Resampling: Enum {
 Where `texture` is resampling suitable for rextures (`average` for scales smaller than 0.5, `cubic` otherwise) 
 and `dem` is suitable for terrain (`average` for scales smaller than 0.5, `cubicspline` otherwise).
 
-Basic resource layout:
+Basic resource definition:
 
 ```javascript
-resource = {
+Object Resource = {
     String comment      // any comment, ignored
     String group        // group this resource belongs to
     String id           // resource identifier (withing group)
@@ -209,12 +225,11 @@ definition = {
     
     String dataset                    // path to complex dataset
     Optional String mask              // optional mask, generated by mapproxy-rf-mask tool
-    Optional Int textureLayerId       // numeric bound layer ID
     Optional String heightcodingAlias // dataset is registered under given alias
 }
 ```
 
-## Geodata
+## Geodata drivers
 
 Geodata drivers generate vector geographic data in the form of VTS free layer.
 
@@ -263,14 +278,11 @@ Browser options override any browser options from associated surface.
 
 ### geodata-vector-tiled
 
-Generates tiled geodata (`geodata-tiles` type) from pre-tiled data. Input tiling must match reference frame's space division,
-at least in one of its nodes. For example, OSM tiles in pseudomerc projection can be used in `webmerc-projected`
-and `webmerc-unprojected` reference frames and in the `pseudomerc` subtree in in `melown2015` reference frame.
+Generates tiled geodata (`geodata-tiles` type) from pre-tiled data like MVT web service or `.mbtiles` archive. Input tiling must match reference frame's space division, at least in one of its nodes. For example, OSM tiles in pseudomerc projection can be used in `webmerc-projected` and `webmerc-unprojected` reference frames and in the `pseudomerc` subtree in in `melown2015` reference frame.
 
-Configuration is the same as for `geodata-vector` driver but input interpretation is different and served data are
-different.
+Configuration is the same as for `geodata-vector` driver but input interpretation is different: option `definition.dataset` is:
+ * for web services: a URL template that is expanded (see above) for each requested tile before opening and processing.
+ * for MBTiles: a path to `.mbtiles` archive with appended template for tiles: `path/to/myvectors.mbtiles/{loclod}-{locx}-{locy}`
 
 Geodata's metatiles are generated purely from heightcoding GDAL dataset.
 
-Option `definition.dataset` is a OGR dataset path/URL template that is expanded for each requested tile before opening
-and processing.