Add mml documentation

[pnorman]

The referenced docs at http://mapbox.com/carto/ do not contain any specifications for .mml files, which carto parses. Docs should be added for these files.

[tmcw]

Hm. There's some documentation of this in the readme. the /carto/ page focuses on Carto via TileMill, and in that cycle the MML is not user-facing. We could possibly cook up better docs as another README section. btw, actual MML parsing is deferred to millstone.

[pnorman]

As an example, try to find the valid values of file from Datasource. The readme gives shape as one valid value, but there are others.

I looked for docs on <Datasource> for Cascadenik MML and it suffers the same problems.

Carto documentation, as opposed to Carto via TileMill, would be a good idea.

[springmeyer]

The underlying cause for this being obscure is that Datasource is simply key:value pairs that get sent to Mapnik and I have an unfinished effort at documenting all the options over at mapnik/mapnik-reference#44

[alexandervlpl]

There is no longer an MML section in the README, and it would be great to have one somewhere in the docs.

I think people are using CartoCSS in their own rendering workflows, which means project.mml is not always an "internal" TileMill / Mapbox Studio config file for them. It's a file that's created and edited manually, and there can be a lot of guesswork involved.

[matkoniecz]

There is no longer an MML section in the README, and it would be great to have one somewhere in the docs.

And from what I see it was just example of beginning of mml file (see 02a657f).

[nebulon42]

Starting on documentation. Notes to self:

• interactivity - Tilemill only feature?
• advanced (layer) - what can go in here?
• queryable (layer attribute) - what is that?

[nebulon42]

I have started on a MML documentation. But I need some help. Could you please read over it and point out what is missing or wrong. Please try also to answer the points I found in #274 (comment).

It would be also nice to know what MML and MSS actually mean. Mapnik Map Layers? Mapnik Style Sheet? Does anybody know? :)

@pnorman @springmeyer @gravitystorm @math1985 @artemp

Link was missing: https://cartocss.readthedocs.io/en/latest/mml.html

[pnorman]

MML and MSS actually mean. Mapnik Map Layers? Mapnik Style Sheet?

MML and MSS both come from Cascadenik. I had always assumed mss stood for map style sheet, but can't find anything explicit.

[gravitystorm]

Maybe @migurski knows what mml and mss originally stood for? In my mind they were just acronyms (XML and CSS -> MML and MSS), so I don't know whether the M was for Mapnik or Map, or even if I'm barking up the wrong tree.

[gravitystorm]

advanced (layer) - what can go in here?

I've used this before for layer attributes that are not defined in cartocss. For example, the shapefile plugin takes an "encoding" attribute, so something like:

     "srs-name": "WGS84",
      "srs": "+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs",
      "advanced": {
        "encoding": "windows-1252"
      },

   <Datasource>
       <Parameter name="file"><![CDATA[/tmp/foo.shp]]></Parameter>
       <Parameter name="type"><![CDATA[shape]]></Parameter>
       <Parameter name="encoding"><![CDATA[windows-1252]]></Parameter>
    </Datasource>

[nebulon42]

@gravitystorm thanks, that's interesting. When I look at the code for layers (https://github.com/mapbox/carto/blob/master/lib/carto/tree/layer.js#L8) then any parameter there should be serialized as parameter tag. So you should be able to specify the encoding of the shapefile directly beneath the datasource property.

[migurski]

I guess I never really defined them, but yeah: MML was Mapnik Markup Language and MSS was Mapnik Stylesheets, both adapted from HTML and CSS terminology. Before Mapbox forked the filename extension, MML was XML. Original blog post here.

[nebulon42]

Thanks @migurski. Why not define them now? :) What about Map Markup Language and Map Stylesheet? While carto targets Mapnik I think it might be good to keep possibilities open.

[nebulon42]

Thanks for the input, I'm closing this as resolved. If there are some features of the MML left undocumented or there are errors I welcome PRs.