Configuration Options for TextSymbolizer

name	This is the query field you want to use for the label text, e.g. "street_name"
face_name	Font name (see UsingCustomFonts)
fontset_name	?
size	Font size
text_ratio	?
wrap_character	Use this character instead of a space to wrap long names (since r1254)
wrap_width	Length before wrapping long names
text_convert	Allows conversion of text to lower or upper case before display. Values are "none" (default), "toupper", and "tolower". (since r1254)
line_spacing	Vertical spacing between lines of multiline labels (in pixels) (since r1254)
character_spacing	Horizontal spacing between characters (in pixels). Currently works for point placement only, not line placement. (since r1254)
spacing	Space between repeated labels
label_position_tolerance	Allow labels to be moved from their point in line placement. Integer value representing distance along a line in line placement mode, defaults to 1/2 min_distance.
force_odd_labels	Force an odd amount of labels to be generated. Defaults to false.
max_char_angle_delta	Maximum angle (in degrees) between two consecutive characters in a label allowed (to stop placing labels around sharp corners) see r365 for more info
fill	Color of the text fill, e.g. #FFFFFF
halo_fill	Color of the text halo
halo_radius	Radius of the halo in whole pixels (fractional pixels are not accepted)
dx, dy	Displace label by fixed amount on either axis. Also see note at vertical_alignment
avoid_edges	Boolean to avoid labeling near intersection edges
min_distance	Minimum distance between repeated labels such as street names or shield symbols (works across features, added in r490)
allow_overlap	Allow labels to overlap other labels - Note: you can also clear the label collision cache at the LAYER level to promote more overlap. See 'clear_label_cache' at wiki:XMLConfigReference#Layer
placement	"line" to label along lines instead of by point
vertical_alignment	Position of label relative to point position ("top" (label on top of point), "middle", "bottom") default is "middle" for dy=0, "bottom" for dy>0, "top" for dy<0 (since r1527, "middle" before that)

Examples

Some examples of Mapnik's ability to place text along lines:

XML

 <TextSymbolizer name="FIELD_NAME" face_name="DejaVu Sans Book" size="10" fill="black" halo_fill= "white" halo_radius="1" placement="line" allow_overlap="false"/>

See XMLGettingStarted for more XML example uses of TextSymbolizer.

Python

t = TextSymbolizer('FIELD_NAME', 'DejaVu Sans Book', 10, Color('black'))
t.halo_fill = Color('white')
t.halo_radius = 1
t.label_placement = label_placement.LINE_PLACEMENT # POINT_PLACEMENT is default
dir(t) # for the rest of the attributes

C++

#include <mapnik/map.hpp>
#include <mapnik/font_engine_freetype.hpp>

using namespace mapnik;
try {
   freetype_engine::register_font("/path/to/font.ttf");
   /* some code */
   rule_type rule;
   text_symbolizer ts("FIELD_NAME", "DejaVu Sans Book", 10, color(0, 0, 0));
   ts.set_halo_fill(color(255, 255, 200));
   ts.set_halo_radius(1);
   rule.append(ts);
}

The first parameter is the field name of a database field, or from a shape file, or an osm file. In case of a shape file or osm file, the field name is case sensitive. You must load the needed fonts first, otherwise you'll get a run time error. But you can load as many true type fonts as you like. Mapnik is coming with a couple of fonts in "mapnik/fonts". I recomend to load all of this fonts, regardless if you need them or not.