Bug 20154 - There are misprints in the spec for "the cairo drawing context" group
Summary: There are misprints in the spec for "the cairo drawing context" group
Status: RESOLVED FIXED
Alias: None
Product: cairo
Classification: Unclassified
Component: general (show other bugs)
Version: 1.8.6
Hardware: All All
: medium minor
Assignee: Carl Worth
QA Contact: cairo-bugs mailing list
URL:
Whiteboard:
Keywords:
Depends on:
Blocks:
 
Reported: 2009-02-17 01:45 UTC by Truc Truong
Modified: 2009-06-03 02:39 UTC (History)
0 users

See Also:
i915 platform:
i915 features:


Attachments

Description Truc Truong 2009-02-17 01:45:07 UTC
There are misprints in the spec and should be corrected. According to us, they are no harm, but the spec will be more clear and reliable if corrected.

- In the spec for cairo_set_antialias(), the standard states:
"Set the antialiasing mode of the rasterizer used for drawing shapes."
 
Change the spec as follows:
"Sets the antialiasing mode of the rasterizer used for drawing shapes."

- In the spec for cairo_get_antialias(), the standard states:
"Gets the current shape antialiasing mode, as set by cairo_set_shape_antialias().
"

Change the spec as follows:
"Gets the current shape antialiasing mode, as set by cairo_set_antialias()."

- In the spec for cairo_set_fill_rule(), the standard states:
"Set the current fill rule within the cairo context."

Change the spec as follows:
"Sets the current fill rule within the cairo context."

- In document 1.8.6, in the spec for cairo_set_line_width(), the standard states:
"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."

Change the spec as follows:
"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_width() and the stroking operation, then one can just pass user-space values to cairo_set_line_width() and ignore this note."

- In document 1.8.6, in the spec for cairo_set_dash(), the standard states:
"If any value in dashes is negative, or if all values are 0, then cr will be put into an error state with a status of #CAIRO_STATUS_INVALID_DASH."

Change the spec as follows:
"If any value in dashes is negative, or if all values are 0, then cr will be put into an error state with a status of CAIRO_STATUS_INVALID_DASH."

- The functions: cairo_set_line_width(), cairo_set_line_join(), cairo_set_line_cap() in document 1.0.2 or later, and cairo_set_miter_limit() in document 1.8.6; made a reference to a function cairo_stroke_to_path() which is not described or specified anywhere in the standard. We could not find any meaningful declaration or implementation of said function in the cairo library source code. 

All references to cairo_stroke_to_path() should be removed.

- In the spec for cairo_stroke_extents(), the standard states:
"Computes a bounding box in user coordinates covering the area that would be affected, (the "inked" area), by a cairo_stroke() operation operation given the current path and stroke parameters."

Remove the extra text as follows:
"Computes a bounding box in user coordinates covering the area that would be affected, (the "inked" area), by a cairo_stroke() operation given the current path and stroke parameters."

- In the spec for cairo_clip_preserve(), the standard states:
"Calling cairo_clip() can only make the clip region smaller, never larger. But the current clip is part of the graphics state, so a temporary restriction of the clip region can be achieved by calling cairo_clip() within a cairo_save()/cairo_restore() pair. The only other means of increasing the size of the clip region is cairo_reset_clip()."

Change the word “cairo_clip()” to “cairo_clip_preserve” as follows:
"Calling cairo_clip_preserve() can only make the clip region smaller, never larger. But the current clip is part of the graphics state, so a temporary restriction of the clip region can be achieved by calling cairo_clip_preserve() within a cairo_save()/cairo_restore() pair. The only other means of increasing the size of the clip region is cairo_reset_clip()."
Comment 1 Chris Wilson 2009-06-03 02:39:31 UTC
(In reply to comment #0)
> There are misprints in the spec and should be corrected. According to us, they
> are no harm, but the spec will be more clear and reliable if corrected.
> 
> - In the spec for cairo_set_antialias(), the standard states:
> "Set the antialiasing mode of the rasterizer used for drawing shapes."
> 
> Change the spec as follows:
> "Sets the antialiasing mode of the rasterizer used for drawing shapes."

I'm favouring the imperative here, they both seem equally poor constructs so I'm not going to change them for the sake of change...
 
> - In the spec for cairo_get_antialias(), the standard states:
> "Gets the current shape antialiasing mode, as set by
> cairo_set_shape_antialias().
> "
> 
> Change the spec as follows:
> "Gets the current shape antialiasing mode, as set by cairo_set_antialias()."

Fixed.

> - In the spec for cairo_set_fill_rule(), the standard states:
> "Set the current fill rule within the cairo context."
> 
> Change the spec as follows:
> "Sets the current fill rule within the cairo context."
> 
> - In document 1.8.6, in the spec for cairo_set_line_width(), the standard
> states:
> "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."
> 
> Change the spec as follows:
> "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_width() and the stroking
> operation, then one can just pass user-space values to cairo_set_line_width()
> and ignore this note."

Mispelling of cairo_set_line_width() fixed.

> - In document 1.8.6, in the spec for cairo_set_dash(), the standard states:
> "If any value in dashes is negative, or if all values are 0, then cr will be
> put into an error state with a status of #CAIRO_STATUS_INVALID_DASH."
> 
> Change the spec as follows:
> "If any value in dashes is negative, or if all values are 0, then cr will be
> put into an error state with a status of CAIRO_STATUS_INVALID_DASH."

The '#' is gtk-doc markup to generate a cross-reference to the definition of CAIRO_STATUS_INVALID_DASH.

> - The functions: cairo_set_line_width(), cairo_set_line_join(),
> cairo_set_line_cap() in document 1.0.2 or later, and cairo_set_miter_limit() in
> document 1.8.6; made a reference to a function cairo_stroke_to_path() which is
> not described or specified anywhere in the standard. We could not find any
> meaningful declaration or implementation of said function in the cairo library
> source code. 
> 
> All references to cairo_stroke_to_path() should be removed.

Won't fix. cairo_stroke_to_path() will be implemented one day.
 
> - In the spec for cairo_stroke_extents(), the standard states:
> "Computes a bounding box in user coordinates covering the area that would be
> affected, (the "inked" area), by a cairo_stroke() operation operation given the
> current path and stroke parameters."
> 
> Remove the extra text as follows:
> "Computes a bounding box in user coordinates covering the area that would be
> affected, (the "inked" area), by a cairo_stroke() operation given the current
> path and stroke parameters."

Duplicate 'operation' removed.

> - In the spec for cairo_clip_preserve(), the standard states:
> "Calling cairo_clip() can only make the clip region smaller, never larger. But
> the current clip is part of the graphics state, so a temporary restriction of
> the clip region can be achieved by calling cairo_clip() within a
> cairo_save()/cairo_restore() pair. The only other means of increasing the size
> of the clip region is cairo_reset_clip()."
> 
> Change the word “cairo_clip()” to “cairo_clip_preserve” as follows:
> "Calling cairo_clip_preserve() can only make the clip region smaller, never
> larger. But the current clip is part of the graphics state, so a temporary
> restriction of the clip region can be achieved by calling cairo_clip_preserve()
> within a cairo_save()/cairo_restore() pair. The only other means of increasing
> the size of the clip region is cairo_reset_clip()."
> 

Text updated to refer to cairo_clip_preserve().


Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.