libXrender - documentation?

[Wichmann, Mats D]

xorg-bounces at lists.freedesktop.org wrote:
> On Wed, 21 Jan 2009, Clemens Eisserer wrote:
>
>> Hi Charles,
>>
>> Unfourtunatly XRender is not very well documented, probably the best
>> thing available is the specification.
>
> hmm - googling on that (xrender specification) doesn't find much -
> just these random notes here for instance:
>
>       http://keithp.com/~keithp/render/protocol.html
>
> which only covers a very small fraction of the library.
>
> (Since it's apparently undocumented - I looked some time ago
> and concluded
> that the documentation covered at most 10% of the code, the "best"
> thing available would appear to be the source code - with the caveat
> that change-history also appears to be lacking).
>
>> The reason is that most programmers use higher-level APIs like Cairo
>> or QT4 to access XRender, so if you don't have a good reason why you
>> directly want to mess with it I recommend using cairo too.
>
> In that case, a pointer to the detailed api of cairo would
> help Charles.

It seems that a library providing an API ought to have docs,
even if the main consumer is another library.  That way the
producer/consumer relationship is codified and there's
actually something to refer to if one or the other changes.

Xrender is in LSB, but is not documented.  As a result,
LSB would be willing to help if there's interest in working
up docs.  Or, alternatively, listen to an argument that a
library like Xrender actually shouldn't be in the spec, that
only cairo should be exposed.