[cairo] negative line widths

[lloyd konneker]

This is about a gotcha, a situation that drove me crazy, using
context.set_line_width().

Essentially my code was:

context.set_line_width(
  context.device_to_user_distance(foo.x, foo.y).x
  )

but then lines were invisible in some situations.  So my fix was:

context.set_line_width(
  abs(context.device_to_user_distance(foo.x, foo.y).x)
  )
  
In some circumstances (for some contexts and CTMs),
device_to_user_distance returns a negative number.  Apparently a
negative line width is invisible?

Should this be a change to the documentation for set_line_width(),
stressing that the parameter should be positive for sensible results?
Also stressing that "distance" is not "length", that distance from A to
B is not the same as distance from B to A in cairo, since one is
negative.

The current documentation "Parameters:	width (float) – a line width" is
contentless.  If it were like documentation for other API calls, it
would tell the limits and type of the parameter, in this case "a length,
a positive distance."

I could be mistaken.  Cairo is great, thanks.

I found an old post that said "Negative line widths must draw the same
as the absolute value in the current Cairo."
http://lists.freedesktop.org/archives/cairo/2006-September/008020.html.
That seems to be a specification for the cairo API.