text-dx, text-dy documentation inaccurate

[stevage]

The documentation for text-dx says: "Displace text by fixed amount, in pixels, +/- along the X axis. A positive value will shift the text right", and text-dy is "Displace text by fixed amount, in pixels, +/- along the Y axis. A positive value will shift the text down"

I don't think this is the full picture. Specifically:

• With "label-placement: simple", I think text-dx controls how far the label will be displaced either left or right. (ie, if the chosen placement is west, then text-dx: 10 means the label will be 10 pixels left)
• With "label-placement: line", text-dx seems to have no effect, but text-dy sets an offset perpendicular to the path. Positive is below the path - but not "down" exactly. (Although sometimes the actual rendering seems to be reversed - perhaps to avoid label collisions.)
• I've also noticed that there's a big difference between text-dx:0 and text-dx:[anything else] for text alignment. Setting a non-zero value seems to automatically shift the alignment to left-justified.

So I think a more accurate statement would be something like:

The horizontal displacement of text, in pixels. In "dummy" placement, a positive value displaces to the right. In "simple" placement, it is either positive or negative, depending on the placement chosen.

and for text-dy:

The vertical displacement of text, in pixels. In "dummy" placement, a positive value displaces downwards. In "simple" placement, it is either positive or negative, depending on the placement chosen. In "line" placement, it displaces perpendicular to the path, positive meaning below the path.

[springmeyer]

Thanks a ton for digging into this. I agree that this doc is not representative of all placement types and needs improvement. Want to queue up a pull request to https://github.com/mapnik/mapnik-reference fixing things? The doc is coming from right here: https://github.com/mapnik/mapnik-reference/blob/ffdce231df9b06f0df48bb27b1ecb1aa6f01ad18/latest/reference.json#L1747-L1758

[stevage]

Ok, done. I confirmed with testing that any non-zero value of text-dx changes the default behaviour of text-horizontal-alignment.

[wheredoesyourmindgo]

Yeah. I had issues with this as well. It was hard to debug, and it appeared that I couldn't apply a 'text-dx' value of less than 3. The fix was for me in Mapbox Studio was to set both the 'text-vertical-alignment' and 'text-horizontal-alignment' value to 'middle'. Then wola! It worked as expected.

[springmeyer]

@wheredoesyourmindgo awesome, thanks for helping figure this out. The right place to improve the docs is by editing the entry in mapnik-reference. I've created mapnik/mapnik-reference#91 to track this: want to provide better wording for the docs based on what you've found?

[wheredoesyourmindgo]

I'd be happy to @springmeyer . I'll toy with all this some more so I have a better understanding of how these properties effect one another; Admittingly I just kinda' hacked my way through all this with little understanding of what was taking place. I think the main thing to point out is that text-dy/text-dx are effected by other properties, which contrasts a bit with SVG transforms such as translate used with marker-transform and the like which seem to behave/operate a bit more independently.