Convert layers to YAML

CONTRIBUTING.md

@@ -10,6 +10,16 @@ You should fork the project into your own repo, create a topic branch
 there and then make one or more pull requests back to the gravitystorm repository.
 Your pull requests will then be reviewed and discussed.
 
+## Editing Layers
+
+OpenStreetMap Carto uses a YAML file for defining layers. Some of the rationale is outlined in [a GitHub issue](https://github.com/gravitystorm/openstreetmap-carto/issues/711). Editing SQL in a YAML file is much friendlier than editing escaped SQL in a JSON file.
+
+This requires a preprocessing step to convert the YAML to JSON. A script is provided at ``scripts/yaml2mml.py``, which depends on PyYAML, available through ``pip install pyyaml`` or packaged on Ubuntu as ``python-yaml``.
+
+After editing the YAML file, run ``./scripts/yaml2mml.py < project.yaml > project.mml && touch project.mml`` to update the file and force TileMill to reload it.
+
+When committing changes, add the entire project.mml file with ``git add project.mml``. One of the big advantages of this system is that to resolve any layer merge conflicts, they only need to be resolved in the YAML file where they are easier to handle, then the JSON file can be regenerated.
+
 ## CartoCSS Style Guidelines
 
 * Always specify zoom levels as either >= or < . Don't use = or =< or >
@@ -18,7 +28,6 @@ Your pull requests will then be reviewed and discussed.
 * Two space indents. No tabs.
 * space after : but not before
 * Dashes, not underscores, in layer names
-* Name SQL subqueries after the layer name (but use underscores)
 * Avoid restating defaults, e.g. don't add `point-allow-overlap = false`
 * Avoid repeating the layer name for layers with mutiple attachments, i.e., prefer
 
@@ -48,6 +57,20 @@ instead of
 ```
 * Order the selectors in a style-sheet in rough order of importance (i.e., highway=primary, then highway=secondary) and beyond that, add layers that are rendered later (i.e., higher) lower in the file.
 
+## SQL Style Guidelines
+Because SQL within JSON or YAML will not generally be syntax highlighted, indentation and caps are particularly important.
+
+* SQL keywords in caps, as in PostgreSQL documentation
+* Two space indents. No tabs.
+* Start with ``(SELECT`` and start the columns on the next line.
+* Two indents for columns, to bring them to the same indent level as later clause contents
+* Add indentation after ``SELECT``s until the end of the sub-select.
+* Add indentation for contents of ``FROM``, ``WHERE``, ``ORDER BY`` and other clauses
+* Put content with WHERE, etc if it's short
+* Add indentation if necessary for complex function calls, WHERE parenthesis, and CASE statements
+* One space before and after = etc
+* Name SQL subqueries after the layer name (but use underscores)
+
 ## Previews
 
 Some changes benefit from a review from a wider audience. In most cases some static images are sufficient, but sometimes a demo layer is necessary. pnorman has a private server which can host layers and has some data from parts of the world loaded. Before requesting this in a pull request, make sure that you don't anticipate any more changes to it.

INSTALL.md

@@ -89,3 +89,5 @@ If you aren't using TileMill, you can compile the CartoCSS stylesheets into Mapn
 * [ogr2ogr](http://www.gdal.org/) command line GDAL utility for processing vector data. here we use it to work around a encoding bug in the Nautral Earth data.
 * curl, unzip for downloading and decompressing files
 * shapeindex (a companion utility to Mapnik found in the mapnik-utils package) for indexing downloaded shapefiles
+
+* [PyYAML] (http://pyyaml.org/wiki/PyYAML) if editing the MML (layer definition) file (packaged as ``python-yaml`` on Ubuntu, or installed with ``pip install pyyaml``)