[cairo] Re: Documentation

[Russell Shaw]

Federico Mena Quintero wrote:
> On Sat, 2006-01-07 at 12:45 +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.
>>Other suggestions for gtk improvements have also been ignored.
>
> Sorry if you have outstanding patches to the GTK+ docs that have not
> been integrated.  I'll be happy to take a look at them.  Do you have
> pointers to them?

Hi,
It was too long ago to remember, so maybe next time. One thing i've always
found missing in gtk is a decent interactive and searchable documents browser
for gtk APIs. The closest i've used is devhelp, but it only barely cuts the
surface as a decent help browser, and has a buggy interactive search function
that doesn't show half the matches when there are more than a few dozen.
I tried to fix that and add other functions, but help from the devhelp list
was less than adequate. With the complexity of the pango api and sparse
documentation on it in trying to make a decent multi-windowing text layout
widget (instead of needing mozillaembed) it got all too hard.

Ironically, i know much more now about gtk, cairo, and text layout only
by learning and writing stuff in Xlib.

Excessive wrappers that hide the underlying system only get in the way of
the developer and stifle flexibility and transparency (understanding) of
the total code base. Plus, new documentation is needed for the wrapper,
but all wrappers have limitations, forcing the developer to learn the
underlying system anyway.

Html docs in a web browser are impractical for a project with multiple
large APIs.