[Xcb] documentation again

[Vincent Torri]

On Fri, 20 Apr 2007, Thomas Hunger wrote:

> Hello,
>
> there was some discussion about documenting the protocol via the xml
> description: e.g.
>
> http://lists.freedesktop.org/archives/xcb/2007-January/002534.html
> http://lists.freedesktop.org/archives/xcb/2006-November/002400.html

Jeremy and I had talked about the doc tags, but, actually, I was waiting 
for the python parser to go on working on it. If you find a better way to 
add documentation in the xml file, please, tell us.

I would also like to add that Alp has done a great job on re-structuring 
the xml description. You can find his work in the spec tag of the git 
repository (from the xcb/ directory, not xcb/libxcb)

> All of X is documented already in the description of the core protocol
> and its extension descriptions. E.g.
>
> http://rfc.net/rfc1013.html
> http://keithp.com/~keithp/render/protocol.html
>
> It's just the format that is very inaccessible. If, somehow, these
> descriptions could get a little extra markup [1], it would be
> possible to merge the names from xcb to the fitting description.

I let Jamey or Josh comment that.

> Now the extensions have been written by different persons in very
> different times, so they lack a uniform format. Maybe it would be
> nice to convert all the protocol descriptions into a uniform format
> (and adding that little bit of extra markup).

I completely agree. More, they need a complete review. Especially, I would 
like to have a link to the description of those protocols. Sometimes, I 
want to review one, but I don't know where to find that doc.

maybe writing a tool (based on python :D) for creating (most of) the xml 
description for the extensions. Like:

./make_proto
$ enum
   * NOM1 val1
   * NOM2 val2
<enter>
$ xid
   * nom
<enter>

etc...

Just a thought...

Vincent