[Xcb] XCB documentation effort

[Josh Triplett]

On Thu, Nov 24, 2011 at 06:36:54PM -0500, Peter Harris wrote:
> On 2011-11-24 17:51, Michael Stapelberg wrote:
> > 
> > I also have a few questions:
> > 
> > 1) Take the CreateGC request:
> 
> >      <valueparam value-mask-type="CARD32"
> >                  value-mask-name="value_mask"
> >                  value-list-name="value_list" />
> 
> >    It obviously supports a bitmask plus some values, which are defined in the
> >    enum GC:
> 
> >    Now my question is: Where is the connection? How can my generator know what
> >    appropriate values for value_mask are?
> 
> There isn't any connection at the moment.
> 
> Traditionally, there have been so few valueparam requests that we've
> just linked them by hand rather than going to the effort of setting up
> proper connections. That said, I'd be happier with a connection in the XML.
> 
> Short-term, adding a "mask=" to <valueparam> could work. Same principle
> as "mask=" on a <field>.
> 
> Long-term, I'd like to deprecate <valueparam> in favour of <switch>.
> This needs discussion and consensus, and I'd prefer to see at least one
> release containing the <switch> in xkb before we apply it to the core
> protocol.
> 
> Input on this issue is very welcome.

Assuming that you mean using <switch> to effectively write a series of
"if value_mask & flag1 then <field type="CARD32" name="field1" />", I
love that idea.  Please do, and please feel free to kill the
special-case valueparam when nothing uses it.

I would argue against the short-term solution, in favor of the long-term
one.  Alternative short-term solution: just hand-write some extra text
in the documentation for those elements, describing how they work, and
don't try to derive it entirely from the XML.

- Josh Triplett