Add basic documentation for scripts

[kocio-pl]

We have just a few scripts in this repo, but none of them is currently documented and their detailed purpose is not obvious. It would be good to include simple comment inside the code and let the script print some informations when called without arguments. Nice README.md would be useful here.

[matkoniecz]

Nice README.md would be useful here.

Probably comment at beginning of the script file would be better.

[kocio-pl]

It was just a serving suggestion 😄 - details are up to script authors.

[matthijsmelissen]

Related stackoverflow question, illustrating how the current situation confused new users: http://gis.stackexchange.com/questions/183459/styling-osm-data-with-osm-carto

[nebulon42]

Slightly OT: When carto 0.16 has been released, it would be possible to get rid of travis_check_project_files and yaml2mml.py as carto will support YAML MML.

And instead of doing distance calculations in generate_road_colours.py it might be possible to use the HuSL perceptual color space, which will also be included in carto 0.16. (See https://github.com/gmgeo/osm-carto-gmgeo/blob/master/style.mss#L138-L141 for an example).

[pnorman]

Slightly OT: When carto 0.16 has been released, it would be possible to get rid of travis_check_project_files and yaml2mml.py

We also need to wait for carto 0.16 to be picked up by at least Kosmtik, and ideally Tilemill as well

And instead of doing distance calculations in generate_road_colours.py it might be possible to use the HuSL perceptual color space, which will also be included in carto 0.16

Distance calculations will still need a conversion to CIELAB. We've been using CIE76 colour-difference for simplicity, and it's defined in Lab. Interpolation should also be done in Lch or Lab.

Given that it all gets converted in the end and the colours are generated by a script and not designed to be edited by hand, we should avoid converting from Lab to HuSL ourselves then HuSL to RGB in Mapnik, as this will introduce more error.

Also, we still need RGB for the road shields.

[springmeyer]

We also need to wait for carto 0.16 to be picked up by at least Kosmtik, and ideally Tilemill as well

Last weekend I got TileMill tests passing again in master (on personal time, not mapbox), so it should be ready for an upgrade of Carto.

[kocio-pl]

Great - with Carto 0.16, TileMill and Kosmtik being ready, we could probably get rid of the MML problem now!

The only remaining question is what Carto version is running on OSM servers?

After the removal Dependencies section in INSTALL.md, Editing Layers in CONTRIBUTING.md and Development dependencies section in INSTALL.md should be updated too.

[gravitystorm]

I don't like saying that you need "tilemill from master" since that doesn't allow people to check if their currently installed version is actually new enough. So I don't think that Tilemill is actually ready, but it will be after the next tag / release of tilemill.

[StyXman]

FYI: Tilemill has not been tagged since October 2012 (at least in the new public repo).

[kocio-pl]

Would it be enough to ask @tmcw for example (as he's active lately) to tag a new release?