[Xcb] XCB documentation effort
josh at joshtriplett.org
Fri Nov 25 18:31:06 PST 2011
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
> 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
More information about the Xcb