From 02a657f3731c0409aaf5c98d33175dd950399cf2 Mon Sep 17 00:00:00 2001 From: Dane Springmeyer Date: Mon, 7 Apr 2014 16:49:27 -0400 Subject: [PATCH] modernize readme and move cascadenik mentions to https://github.com/mapbox/carto/wiki/Differences-With-Cascadenik --- README.md | 324 ++++++++++++++++++++++-------------------------------- 1 file changed, 134 insertions(+), 190 deletions(-) diff --git a/README.md b/README.md index 1861fc8..4b15e55 100644 --- a/README.md +++ b/README.md @@ -2,124 +2,128 @@ [![Build Status](https://secure.travis-ci.org/mapbox/carto.png)](http://travis-ci.org/mapbox/carto) -Is a stylesheet renderer for Mapnik. It's an evolution of the -[Cascadenik](https://github.com/mapnik/Cascadenik) idea and language, -with an emphasis on speed and flexibility. +Is the language for map design used by [TileMill](). It is similiar in syntax to CSS, but builds upon it with specific abilities to filter map data and by providing things like variables. -## Reference Documentation +Carto, aka CartoCSS, targets the [Mapnik renderer](http://mapnik.org) and is able to general Mapnik XML> -* [mapbox.com/carto](http://mapbox.com/carto/) +Carto is an evolution of the [Cascadenik](https://github.com/mapnik/Cascadenik) idea and language, +with an emphasis on speed and flexibility. If you are a previous user of Cascadenik, see the [key differences wiki](https://github.com/mapbox/carto/wiki/Differences-With-Cascadenik). -## MML -_incompatibility_ +## Documentation -* MML files are assumed to be JSON, not XML. The files are near-identical - to the XML files accepted by Cascadenik, just translated into JSON. -* CartoCSS will not embed files or download URLs for you. Stylesheets should - be embedded directly into your MML JSON and any datasources should be - paths (relative or absolute) that would be acceptable in Mapnik XML. - The [millstone project](https://github.com/mapbox/millstone) aims to fill this need. +For users looking to learn how to use TileMill the best places to start are to 1) Download [TileMill](http://mapbox.com/carto/) and review the [Carto reference documentation](http://mapbox.com/carto/). -CartoCSS MML: +Tutorials like the [TileMill Crashcourse](https://www.mapbox.com/tilemill/docs/crashcourse/styling/) are a great place to start to learn the basics of CartoCSS. - { - "srs": "+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over", - "Stylesheet": [{"id":"style.mss","data":"Map {\n background-color: #fff;\n}\n\n#world {\n line-color: #ccc;\n line-width: 0.5;\n polygon-fill: #eee;\n}"}], - "Layer": [{ - "id": "world", - "name": "world", - "srs": "+proj=latlong +ellps=WGS84 +datum=WGS84 +no_defs", - "Datasource": { - "file": "world_borders", - "type": "shape" +For more advanced topics see: + + - [Details on Filtering data with CartoCSS](https://www.mapbox.com/tilemill/docs/guides/selectors/) + - [How order works in rendering](https://www.mapbox.com/tilemill/docs/guides/symbol-drawing-order/) + - [How to style labels](https://www.mapbox.com/tilemill/docs/guides/styling-labels/) + - [How to style lines](https://www.mapbox.com/tilemill/docs/guides/styling-lines/) + - [How to style polygons](https://www.mapbox.com/tilemill/docs/guides/styling-polygons/) + +## Developers + +#### Installation + +If you're using [TileMill](http://mapbox.com/tilemill/), you're already +using CartoCSS and don't need to do a thing. + +If you're a developer-type and want to use the `carto` binary with +`node.js` (and you have [npm](http://npmjs.org/) installed), + + npm install -g carto + +Optionally you may also want to install millstone which is required for resolving data in the same way as TileMill does: + + npm install -g millstone + + +Having `millstone` installed specifically enable support for localizing external resources (URLs and local files) referenced in your mml file, and detecting projections (using [node-srs](https://github.com/mapbox/node-srs)) + +Now that Carto is installed you should have a `carto` command line tool available that can be run on a TileMill project: + + carto project.mml > mapnik.xml + +#### From code + +Currently CartoCSS is designed to be invoked from [node.js](http://nodejs.org/). +The `Renderer` interface is the main API for developers, and it takes an MML file as a string as input. + + // defined variables: + // - input (the name or identifier of the file being parsed) + // - data (a string containing the MML or an object of MML) + var carto = require('carto'); + + new carto.Renderer({ + filename: input, + local_data_dir: path.dirname(input), + }).render(data, function(err, output) { + if (err) { + if (Array.isArray(err)) { + err.forEach(function(e) { + carto.writeError(e, options); + }); + } else { throw err; } + } else { + sys.puts(output); } - }] - } + }); -Cascadenik MML +### Vim -
<Stylesheet><![CDATA[
-    Map {
-        map-bgcolor: #69f;
-    }
+To install, download or clone this repository, then add the `vim-carto`
+directory located at `build/vim-carto` to your `~/.vim` file.
 
-    Layer {
-        line-width: 1;
-        line-color: #696;
-        polygon-fill: #6f9;
-    }
-]]></Stylesheet>
-<Layer srs="+proj=latlong +ellps=WGS84 +datum=WGS84 +no_defs">
-    <Datasource>
-        <Parameter name="type">shape</Parameter>
-        <Parameter name="file">world_borders</Parameter>
-    </Datasource>
-</Layer>
-</Map>
+## Credits -## Attachments and Instances -_new_ +CartoCSS is based on [less.js](https://github.com/cloudhead/less.js), a CSS compiler written by Alexis Sellier. + +It depends on: + +* [underscore.js](https://github.com/documentcloud/underscore/) + +Only for running tests: + +* [mocha](https://github.com/visionmedia/mocha) +* [sax-js](https://github.com/isaacs/sax-js/) + +## Technical Syntax details + +### Attachments and Instances In CSS, a certain object can only have one instance of a property. A `
` has a specific border width and color, rules that match better than others (#id instead of .class) override previous definitions. `CartoCSS` acts the same way normally for the sake of familiarity and organization, but Mapnik itself is more powerful. Layers in Mapnik can have multiple [borders](http://trac.mapnik.org/wiki/LineSymbolizer) and multiple copies of other attributes. This ability is useful in drawing line outlines, like in the case of road borders or 'glow' effects around coasts. `CartoCSS` makes this accessible by allowing attachments to styles: - #world { - line-color: #fff; - line-width: 3; - } +```css +#world { + line-color: #fff; + line-width: 3; +} - #world::outline { - line-color: #000; - line-width: 6; - } +#world::outline { + line-color: #000; + line-width: 6; +} +``` -Attachments are optional: if you don't define them, CartoCSS does overriding of styles just like Cascadenik. - -This brings us to another _incompatibility_: `line-inline` and `line-outline` have been removed from the language, because attachments are capable of the same trick. +Attachments are optional. While attachments allow creating implicit "layers" with the same data, using **instances** allows you to create multiple symbolizers in the same style/layer: - #roads { - casing/line-width: 6; - casing/line-color: #333; - line-width: 4; - line-color: #666; - } +```css +#roads { + casing/line-width: 6; + casing/line-color: #333; + line-width: 4; + line-color: #666; +} +``` This makes Mapnik first draw the line of color #333 with a width of 6, and then immediately afterwards, it draws the same line again with width 4 and color #666. Contrast that to attachments: Mapnik would first draw all casings before proceeding to the actual lines. -## text-name -_incompatibility_ - -Instead of the name attribute of the [TextSymbolizer](http://trac.mapnik.org/wiki/TextSymbolizer) and [ShieldSymbolizer](http://trac.mapnik.org/wiki/ShieldSymbolizer) being a part of the selector, it is a property of a rule. Thus the evaluation is less complex and one can use expressions in names. - - - - - - - - - - -
cascadenikCartoCSS
- 
-#world NAME {
-  text-face-name: "Arial";
-}
- 		- 
-#world {
-  text-name: "NAME";
-  text-face-name: "Arial";
-}
-
- -## Mapnik -_new_ - -CartoCSS is only compatible with Mapnik >= 2.x.x. ## Rasters and Buildings _new_ @@ -129,54 +133,56 @@ Rasters are supported in CartoCSS - it knows how to download `.vrt`, `.tiff`, an The [BuildingSymbolizer](http://trac.mapnik.org/wiki/BuildingSymbolizer) is also supported in `CartoCSS`. The code stores symbolizer types and properties in a JSON file (in `tree/reference.json`), so new Mapnik features can be quickly implemented here. ## Variables & Expressions -_new_ CartoCSS inherits from its basis in [less.js](http://lesscss.org/) some new features in CSS. One can define variables in stylesheets, and use expressions to modify them. - @mybackground: #2B4D2D; - - Map { - background-color: @mybackground - } - - #world { - polygon-fill: @mybackground + #222; - line-color: darken(@mybackground, 10%); - } +```css +@mybackground: #2B4D2D; + +Map { + background-color: @mybackground +} + +#world { + polygon-fill: @mybackground + #222; + line-color: darken(@mybackground, 10%); +} +``` ## Nested Styles -_new_ CartoCSS also inherits nesting of rules from less.js. - /* Applies to all layers with .land class */ - .land { - line-color: #ccc; - line-width: 0.5; - polygon-fill: #eee; - /* Applies to #lakes.land */ - #lakes { - polygon-fill: #000; - } - } +```css +/* Applies to all layers with .land class */ +.land { + line-color: #ccc; + line-width: 0.5; + polygon-fill: #eee; + /* Applies to #lakes.land */ + #lakes { + polygon-fill: #000; + } +} +``` This can be a convenient way to group style changes by zoom level: - [zoom > 1] { - /* Applies to all layers at zoom > 1 */ - polygon-gamma: 0.3; - #world { - polygon-fill: #323; - } - #lakes { - polygon-fill: #144; - } - } +```css +[zoom > 1] { + /* Applies to all layers at zoom > 1 */ + polygon-gamma: 0.3; + #world { + polygon-fill: #323; + } + #lakes { + polygon-fill: #144; + } +} +``` ## FontSets -_new_ - By defining multiple fonts in a `text-face-name` definition, you create [FontSets](http://trac.mapnik.org/wiki/FontSet) in `CartoCSS`. These are useful for supporting multiple character sets and fallback fonts for distributed styles. @@ -237,68 +243,6 @@ String comparisons: #world[name =~ "A.*"] ``` -## Developers - -#### Installation - -If you're using [TileMill](http://mapbox.com/tilemill/), you're already -using CartoCSS and don't need to do a thing. - -If you're a developer-type and want to use the `carto` binary with -`node.js` (and you have [npm](http://npmjs.org/) installed), - - npm install -g carto - -#### From the binary - -Install `millstone` to enable support for localizing external resources (URLs and local files) referenced in your mml file. - - npm install millstone - carto map_file.json - -#### From code - -Currently CartoCSS is designed to be invoked from [node.js](http://nodejs.org/). -The `Renderer` interface is the main API for developers, and it takes an MML file as a string as input. - - // defined variables: - // - input (the name or identifier of the file being parsed) - // - data (a string containing the MML or an object of MML) - var carto = require('carto'); - - new carto.Renderer({ - filename: input, - local_data_dir: path.dirname(input), - }).render(data, function(err, output) { - if (err) { - if (Array.isArray(err)) { - err.forEach(function(e) { - carto.writeError(e, options); - }); - } else { throw err; } - } else { - sys.puts(output); - } - }); - -### Vim - -To install, download or clone this repository, then add the `vim-carto` -directory located at `build/vim-carto` to your `~/.vim` file. - -## Credits - -CartoCSS is based on [less.js](https://github.com/cloudhead/less.js), a CSS compiler written by Alexis Sellier. - -It depends on: - -* [underscore.js](https://github.com/documentcloud/underscore/) - -Only for running tests: - -* [mocha](https://github.com/visionmedia/mocha) -* [sax-js](https://github.com/isaacs/sax-js/) - ## Authors * Tom MacWright (tmcw)