update docs

Author: talaj

README.md

@@ -4,15 +4,17 @@ This repository contains a fork of [github.com/mapnik/mapnik](https://github.com
 
 * [Tree-like layer structure](docs/features/layer-structure.md)
 * [Layer level compositing](docs/features/layer-level-compositing.md)
+* [Unification of placement code](docs/features/placement-code-unified.md)
+* [Placement `grid` and `alternating-grid`](docs/features/placement-grid.md)
+* [CollisionSymbolizer](docs/features/collision-symbolizer.md)
+* [Keyed collision caches](docs/features/keyed-collision-caches.md)
 * [Text placement method `combined`](docs/features/text-placement-combined.md)
 * [Text placement method `angle`](docs/features/text-placement-angle.md)
 * [Anchors](docs/features/anchors.md)
-* [Text placement `grid`](docs/features/text-placement-grid.md)
+* [Pattern symbolizers improvements](docs/features/pattern-symbolizers.md)
 * [Text on extended geometry](docs/features/text-extend.md)
 * [Shadows with building symbolizer](docs/features/building-symbolizer-shadow.md)
 * [XSLT preprocessing](docs/features/xslt-preprocessing.md)
-* Offsetting algorithm
-* Constant height of a first text line
 
 # Mapnik
 

docs/features/collision-symbolizer.md

@@ -0,0 +1,10 @@
+# `CollisionSymbolizer`
+
+It's sometimes convinient to "render" some invisible labels and insert them into collision detector in order to protect their places agains other objects. This can be done by `TextSymbolizer` or `MarkersSymbolizer` with `opacity="0"` but it comes with unnecessary performance overhead of text or marker rendering and seems like hackish solution in general.  The `CollisionSymbolizer` solves that.
+
+## An example
+
+[collision-symbolizer-4.xml](https://github.com/mapycz/test-data-visual/blob/master/styles/collision-symbolizer-4.xml)
+
+![collision-symbolizer-4](https://raw.githubusercontent.com/mapycz/test-data-visual/master/images/collision-symbolizer-4-800-800-1.0-agg-reference.png)
+

docs/features/keyed-collision-caches.md

@@ -0,0 +1,25 @@
+# Keyed collision caches
+
+All symbolizers working with collision detector have parameters `collision-cache-detect` and `collision-cache-insert`. These parameters set names of collision detectors. Multiple names delimited by comma are supported. If one of these parameters is not defined, collision detector with name `default` is used instead. The `default` collision detector can be referenced explicitly.
+
+An example of inserting objects only into collision detector called `water`:
+
+```
+collision-cache-insert="water"
+```
+
+An example of detection against collision detector called `water` and default collision detector:
+
+```
+collision-cache-detect="water,default"
+```
+
+## `DebugSymbolizer`
+
+`DebugSymbolizer` has parameter `collision-cache` for comma separated list of collision detectors to visualize. If `collision-cache` is not set, all objects of all collision detectors are visualized.
+
+## An example
+
+[collision-cache-1.xml](https://github.com/mapycz/test-data-visual/blob/master/styles/collision-cache-1.xml)
+
+![collision-cache-1](https://raw.githubusercontent.com/mapycz/test-data-visual/master/images/collision-cache-1-800-800-1.0-agg-reference.png)

docs/features/pattern-symbolizers.md

@@ -0,0 +1,39 @@
+# Pattern symbolizers improvements
+
+## Better SVG support
+
+Both `LinePatternSymbolizer` and `PolygonPatternSymbolizer` can customize SVG pattern by parameters
+
+* `fill`
+* `fill-opacity`
+* `stroke`
+* `stroke-width`
+* `stroke-opacity`
+
+### An example
+
+[polygon-pattern-2.xml](https://github.com/mapycz/test-data-visual/blob/master/styles/polygon-pattern-2.xml)
+
+![polygon-pattern-2](https://raw.githubusercontent.com/mapycz/test-data-visual/master/images/polygon-pattern-2-256-256-1.0-agg-reference.png)
+
+## Parameter `spacing`
+
+Parameter `spacing` of `PolygonPatternSymbolizer` sets spacing between individual images of given pattern.
+
+### An example
+
+[polygon-pattern-6.xml](https://github.com/mapycz/test-data-visual/blob/master/styles/polygon-pattern-6.xml)
+
+![polygon-pattern-6](https://raw.githubusercontent.com/mapycz/test-data-visual/master/images/polygon-pattern-6-256-256-1.0-agg-reference.png)
+
+## Parameter `lacing`
+
+Parameter `lacing` of `PolygonPatternSymbolizer` set to `alternating-grid` will render pattern resembling bricks in a wall. Value `grid` is the default when parameter is unset.
+
+### An example
+
+[polygon-pattern-3.xml](https://github.com/mapycz/test-data-visual/blob/master/styles/polygon-pattern-3.xml)
+
+![polygon-pattern-3](https://raw.githubusercontent.com/mapycz/test-data-visual/master/images/polygon-pattern-3-256-256-1.0-agg-reference.png)
+
+

docs/features/placement-code-unified.md

@@ -0,0 +1,24 @@
+# Unification of placement code
+
+All these symbolizers have common purpose - placing labels on some geometric positions:
+
+* `TextSymbolizer`
+* `ShieldSymbolizer`
+* `GroupSymbolizer`
+* `MarkersSymbolizer`
+* `PointSymbolizer`
+* `CollisionSymbolizer`
+
+It makes sense to allow all possible placement options for all these symbolizers. Therefore all these symbolizers support all these placement options:
+
+* `point`
+* `interior`
+* `centroid`
+* `line`
+* `vertex`
+* `vertex-first`
+* `vertex-last`
+* `grid`
+* `alternating-grid`
+
+This unification is a result of great code sharing and simple [declarative description](https://github.com/mapycz/mapnik/blob/63ed040a3c1817db8b5a3f1333dccc9fb5d42f8b/include/mapnik/text/symbolizer_helpers.hpp#L57-L106) of each symbolizer.

docs/features/placement-grid.md

@@ -0,0 +1,27 @@
+
+# Placement `grid` and `alternating-grid`
+
+Allows placing repeated labels on area of a polygon. All possible placements create grid of points. Only placements within given polygon are rendered.
+
+`alternating-grid` creates pattern similar to bricks in a wall.
+
+Very important is order in which grid is iterated and individual placements placed. The first point is polygon's interior. Subsequent placements go around interior in a spiral.
+Only `CollisionSymbolizer` does not work this way, but rather iterates the grid in left-right top-down order.
+
+These are basic use cases:
+
+* Labeling areas in given density.
+* Trying various positions around interior.
+* Adding areas into collision detector by `CollisionSymbolizer`.
+
+Grid density can be controlled by `grid-cell-width` and `grid-cell-height` properties of the symbolizer.
+
+## An example
+
+[grid-on-polygon-3.xml](https://github.com/mapycz/test-data-visual/blob/master/styles/grid-on-polygon-3.xml)
+
+![grid-on-polygon-3](https://raw.githubusercontent.com/mapycz/test-data-visual/master/images/grid-on-polygon-3-800-800-1.0-agg-reference.png)
+
+[grid-on-polygon-1-marker-alternating.xml](https://github.com/mapycz/test-data-visual/blob/master/styles/grid-on-polygon-1-marker-alternating.xml)
+
+![grid-on-polygon-1-marker-alternating](https://raw.githubusercontent.com/mapycz/test-data-visual/master/images/grid-on-polygon-1-marker-alternating-800-800-1.0-agg-reference.png)

docs/features/text-extend.md

@@ -1,7 +1,7 @@
 
 # Text on extended geometry
 
-Allows to render text along line when length of the text exceeds length of the line. Beginning and ending segments of the underlaying line are extended by number of pixes given by parameter `extend`.
+Allows to render text along line when length of the text exceeds length of the line. Beginning and ending segments of the underlaying line are extended by number of points given by parameter `extend`.
 
 ## An example