[Xcb] documentation patches

[Alex Plotnick]

Michael Stapelberg writes:

> It’s been two months without any progress on this (no new feedback/reviews).

Perhaps I haven't been part of the XCB development community long enough
for anyone to care about my opinion, but I have a few things to say
about this patch.

First off, I appreciate that it must have been a huge amount of work to
prepare, and I applaud the effort. Lack of good documentation is one of
the biggest problems in working with many free software packages, and
people that step up to the plate and actually write docs are rare and
valuable. So: thank you.

That said, I have some objections to the actual docs themselves. The
largest general objection that I have is that the XML protocol
description is not the right place for language- and API-specific
documentation. The X protocol is very intentionally language- and
API-agnostic, and bindings for languages other than C and APIs other
than libxcb can be and are generated from the same protocol
descriptions. When I'm using xpyb, I don't care about what libxcb does
with a particular request or event, and a name like `XCB_CURRENT_TIME`
or `XCB_NONE` doesn't do me any good.

Moreover, we have an excellent and complete description of the X
protocol: the X protocol specification. I can't see any reason to
paraphrase or duplicate the spec when we have the authoritative original
already in a form that, with a little bit of work, could serve the same
purpose as what you propose. The protocol documents are already in an
XML format (DocBook/XML); with a bit of XSLT (or maybe a simple script,
possibly coupled with some improvements to the markup of the spec
itself), they could almost certainly be re-purposed to provide precise
and essentially error-free versions of the kind of descriptions you
offer in your patch. I'm sure I'm not alone in that when I'm using XCB
(in whatever form), I *always* have a copy of the spec open in front of
me; it would be useful, I'm sure, to have the XCB protocol descriptions
and the actual specification tied together in some nice, automated way.

Leaving that issue aside for a the moment, however, I also think that
the docs you submitted still need a lot of work. In addition to the
issues that Uli pointed out, there are some very obvious copy-and-paste
errors; e.g., the detail field of a button press does not contain "The
keycode ... of the key which was pressed". That was the first one that
jumped out at me; there are others.

But more important are the semantic problems. I'll pick a few examples,
more or less at random. A timestamp isn't exactly the "Time when the
event was generated" (the gloss you use in Key/ButtonPress and
MotionNotify). The spec uses the phrase "server time" in a few places,
but the glossary entry make it clear this is a technical term with a
specific meaning; it's not a wall-clock time, and it can and does
wrap around. The override-redirect attribute doesn't actually mean
"Window managers should ignore this window"; it's generally set so
that window managers will ignore the window, but that's not what it
*means*. And atoms aren't just "used in protocols like EWMH"; they're
identifiers with string names that are "used to identify properties,
types, and selections" (from the glossary). I hope that you don't just
take this as me being pedantic; these are important issues that are
fundamental to writing good X clients, and providing overly-simplified
or misleading descriptions of them will, I think, lead people down the
wrong path.

I understand the idea that some documentation is better than none, but
I don't think it applied in this case: we have documentation (the spec);
what we don't have is it hooked up in a nice way to the functions that
people need to use in their applications, or examples of how to use
them. So I do still think there's an important place for the kind of
documentation you provided in your patch, or at least parts of it. In
particular, the examples could be extremely valuable. I just don't think
they belong in the protocol description.

Sorry this ended up being so long. But XCB is an increasingly important
part of the X ecosystem, and although I certainly think it's important
that documentation be available, I also think that it's even more
important that it be precise and well-targeted.


        -- Alex