[Xcb] documentation patches

[Josh Triplett]

On Mon, Mar 26, 2012 at 01:21:25PM -0400, Alex Plotnick wrote:
> 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.

Seconded.

> 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.

I think these issues all go together, actually.  Adding documentation to
XCB has quite a bit of value, but rewriting the X protocol documentation
from scratch doesn't, and it leads to precisely these kinds of subtle
issues.  I'd strongly recommend using the technical changes you've made
as a base (constructing manpages and embedding documentation) and
merging in the X protocol documentation to provide the actual text.
(That text might well need editing, but merge it in verbatim at first.)
Ideally, you could then start generating the current X protocol
documentation from the XCB descriptions, so that both the structure
definitions and the documentation had a single canonical source.

- Josh Triplett