Codify 1.0 behavior of cairo_set_line_width as a feature, not a bug.

Clarify the documentation of cairo_set_line_width to indicate that the
value will be interpreted within the user space at the time of the
stroke.

Also adjust the comments in test/line-width-scale as well as the
reference images for that test to match.

src/cairo.c

@@ -802,16 +802,28 @@ cairo_set_fill_rule (cairo_t *cr, cairo_fill_rule_t fill_rule)
 /**
  * cairo_set_line_width:
  * @cr: a #cairo_t
- * @width: a line width, as a user-space value
+ * @width: a line width
  * 
  * Sets the current line width within the cairo context. The line
- * width specifies the diameter of a pen that is circular in
- * user space.
+ * width value specifies the diameter of a pen that is circular in
+ * user space, (though device-space pen may be an ellipse in general
+ * due to scaling/shear/rotation of the CTM).
+ *
+ * Note: When the description above refers to user space and CTM it
+ * refers to the user space and CTM in effect at the time of the
+ * stroking operation, not the user space and CTM in effect at the
+ * time of the call to cairo_set_line_width(). The simplest usage
+ * makes both of these spaces identical. That is, if there is no
+ * change to the CTM between a call to cairo_set_line_with() and the
+ * stroking operation, then one can just pass user-space values to
+ * cairo_set_line_width() and ignore this note.
  *
  * As with the other stroke parameters, the current line width is
  * examined by cairo_stroke(), cairo_stroke_extents(), and
  * cairo_stroke_to_path(), but does not have any effect during path
  * construction.
+ *
+ * The default line width value is 2.0.
  **/
 void
 cairo_set_line_width (cairo_t *cr, double width)
@@ -2591,9 +2603,10 @@ cairo_get_fill_rule (cairo_t *cr)
  * cairo_get_line_width:
  * @cr: a cairo context
  * 
- * Gets the current line width, as set by cairo_set_line_width().
- * 
- * Return value: the current line width, in user-space units.
+ * Return value: the current line width value exactly as set by
+ * cairo_set_line_width(). Note that the value is unchanged even if
+ * the CTM has changed between the calls to cairo_set_line_width() and
+ * cairo_get_line_width().
  **/
 double
 cairo_get_line_width (cairo_t *cr)

test/line-width-scale.c

@@ -26,7 +26,7 @@
 #include "cairo-test.h"
 
 /* This test exercises the various interactions between
- * cairo_set_line_width and cairo_scale. Specifically it show how
+ * cairo_set_line_width and cairo_scale. Specifically it shows how
  * separate transformations can affect the pen for stroking compared
  * to the path itself.
  *
@@ -35,11 +35,14 @@
  *
  *	http://antigrain.com/tips/line_alignment/conv_order.gif
  *
- * It also uncovered a bug in cairo that cairo_set_line_width was not
- * transforing the width according the the current CTM, but instead
- * delaying that transformation until the time of cairo_stroke. See:
+ * It also uncovered some behavior in cairo that I found surprising.
+ * Namely, cairo_set_line_width was not transforming the width
+ * according the the current CTM, but instead delaying that
+ * transformation until the time of cairo_stroke.
  *
- *	http://article.gmane.org/gmane.comp.graphics.agg/2518
+ * This delayed behavior was released in cairo 1.0 so we're going to
+ * document this as the way cairo_set_line_width works rather than
+ * considering this a bug.
  */
 
 #define LINE_WIDTH 13
@@ -106,12 +109,12 @@ scale_path_and_line_width (cairo_t *cr)
     cairo_restore (cr);
 }
 
-/* This one's the bug.
+/* This is the case that was surprising.
  *
- * If we set the line width before scaling, then the path should be
- * scaled but the line width should not.
- *
- * With the bug, the line_width is also being scaled here.
+ * Setting the line width before scaling doesn't change anything. The
+ * line width will be interpreted under the CTM in effect at the time
+ * of cairo_stroke, so the line width will be scaled as well as the
+ * path here.
  */
 static void
 set_line_width_then_scale_and_stroke (cairo_t *cr)
@@ -122,10 +125,9 @@ set_line_width_then_scale_and_stroke (cairo_t *cr)
     cairo_stroke (cr);
 }
 
-/* This is used to verify what should be the results of
- * set_line_width_then_scale_and_stroke (once the bug is fixed).
+/* Here then is the way to achieve the alternate result.
  *
- * It uses save/restore pairs to isolate the scaling of the path and
+ * This uses save/restore pairs to isolate the scaling of the path and
  * line_width and ensures that the path is scaled while the line width
  * is not.
  */