[cairo] Re: Documentation

[Carl Worth]

On Sat, 07 Jan 2006 12:45:50 +1100, Russell Shaw wrote:
> I spent many hours in making a documentation patch detailing the cairo
> api and how the porter-duff rendering works, only to have it ignored.

Hi Russell,

Is this the patch you're referring to?

http://lists.freedesktop.org/archives/cairo/2005-August/004915.html

I apologize for not having responded to it earlier, but frankly it
looked more like a bug report against gtk-doc with a documentation
patch attached as a test case, rather than an offer for something to
be included with cairo's documentation.

We currently have no real documentation for cairo_operator_t other
than the names of the operators themselves. What we really need first,
is good prose descriptions of the operators to guide users in
selecting an operator based on something they want to do. This could
describe common uses such as the default OVER for blending potentially
transparent objects, CLEAR for erasing to transparent, SOURCE for
copying a source image exactly including any translucence, while
ignoring the background, DEST_OUT for "cutting a hole" into a picture,
etc.

Beyond that, there is a separate need for a separate section with all
the gory details of cairo's rendering model, with full equations. This
would not be specific to cairo_operator_t since every rendering
operation, (cairo_stroke, cairo_fill, cairo_show_glyphs), would need
to refer to it. The detail in this section should not be necessary for
"casual" use of cairo, but will be needed for people with particular
technical needs or morbid curiosity. For example, this section would
help people implementing new cairo backends, using cairo to implement
some other graphics system given a similar technical level of detail,
or performing careful verification of cairo's output, etc.

The patch you proposed is worded in the style of the more detailed
section, but really only scratches the surface of what needs to be
there. Some of that is due to the fact that right up until the cairo
1.0 release, some of the fundamental details of cairo's rendering
model kept changing. For instance, your patch has:

	dest = (source OP_IN mask) <OP> dest

which is valid for describing the operation performed by cairo for some
cases of <OP> but not for all. The actual equations used are currently
captured in the code itself, and the rationale is captured in email
discussions. That's not a useful final resting place for the
rationale, so I do plan to move that into the detailed section of
documentation I referred to above when I work on that.

So there's a high-level explanation of why I didn't commit the
documentation patch you offered. There are more detailed critiques I
could offer, but they're not really useful to provide given the
high-level issues.

> When non-existant documentation raises the learning curve to a certain
> level, it's easier to write your own libs that you can be intimately
> familiar with and does everything better, faster, and with *far* less
> but more elegant code.

Maybe we should each "rm -rf /usr/share/doc" then and start over so we
can all be intimately familiar with our own better, faster, smaller,
more elegant code then? I'd better get started. ;-)

-Carl
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/cairo/attachments/20060109/4692a341/attachment.pgp