brave newbie vs. xorg-docs

[Carlo Salinari]

Jamey Sharp wrote:
> On Thu, Dec 07, 2006 at 10:59:29AM +0100, Carlo Salinari wrote:
>   
>> As I understand there has been some discussion about migrating xorg 
>> documentation to some new format.
>>     
>
> I see two major remaining parts to this project, aside from the fine
> work that David Nusinow and Eamon Walsh have been doing recently on
> maintaining the existing SGML documentation.
>
> Most discussion so far has been about converting various X-related
> specification documents from a variety of formats, including troff,
> LaTeX, Framemaker, Word, etc., to Docbook.
> http://gitweb.freedesktop.org/?p=xorg/doc/xorg-docs.git;a=tree;hb=HEAD;f=specs
>   
Alright. One wild formats zoo to tame and some SGML documentation to 
rejuvenate.

> For protocol documentation, however, we'd like the xcb-proto project to
> become the central repository. Currently, xcb-proto contains
> machine-readable XML descriptions of the binary encoding of the X
> protocol and extensions. The XML tagset needs to be extended to allow
> Docbook annotations to be attached to the protocol elements; we need a
> transformer (probably an XSLT stylesheet) that generates full Docbook
> documents from the specifications; and finally, of course, people need
> to copy all the descriptive text in and validate the binary encoding
> descriptions.
>   
This sounds very interesting, but I'm afraid my present knowledge of the 
xcb inner workings is rather superficial.
> Jeremy Kolb and others have written down some thoughts on the protocol
> documentation project in the XCB list archives, and if you're interested
> in that part I'd invite you to come chat with us about it there:
> 	http://lists.freedesktop.org/mailman/listinfo/xcb
>   
Thanks, I've just subscribed to the list.

> If the first project is more your style, I hope somebody else will
> comment on the work involved (gravity? jg?).
>   

I think I'll have a look around, and find something simple to start 
with. Meanwhile, I'll try to learn something more about
xcb's code generation and xcb-proto in general.

Thank you,
    Carlo