[cairo] GSoC Project - API Reference to wiki port

[Carl Worth]

On Wed, 2 Apr 2008 15:50:23 -0500, "Bill Weepie" wrote:
> Ah, my mistake.  This project idea was listed on Cairo's SoC ideas page, and
> I was trying to gauge interest in the project idea before submitting a
> formal application.  I should've read Google's FAQ more carefully.
>
> Sorry to waste your time,

No apology necessary, Bill!

We're the ones that put an invalid idea up on our idea page (oops!).

Meanwhile, discussion of improving our documentation is still quite
useful.

While we might have some docbook source in the tree, we have very
little and I'm sure there's almost no markup in it, (I'd be surprised
if there's anything more than paragraph breaks).

Most of our API documentation exists in the source code itself, with
gtk-doc format.

One reason I don't like the in-source documentation is that we really
want documentation that goes beyond "this function performs this
task". We really need introductory chapters on cairo's rendering
model, how error-handling works in cairo, background information on
compositing operations and the detailed arithmetic of the compositing
operations, etc. And I just don't think that kind of thing works well
at all with in-source documentation.

Mostly, though, I think tool discussion is the lesser problem of
cairo's documentation. We really need more of the content like I
described above. And generating content like that isn't the kind of
thing that could be done by someone with little prior knowledge of
cairo.

But shuffling existing content around and moving things from gtk-doc
to all be in markdown format, (or whatever), could certainly be done
by anyone with knowledge and interest in the formats, but without
needing deep knowledge of the content. So that's why that seemed a
useful idea for Summer of Code---just that we missed the fact that
it's not within Google's policy.

But of course, it's still a useful project if anybody would like to
help with it. If so, thanks in advance!

-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.cairographics.org/archives/cairo/attachments/20080402/f46b4a43/attachment.pgp