[Xcb] Re: [Xcb-commit] Branch 'xspec' - xcb-proto

[Barton C Massey]

Alp,

I think we hadn't realized that you were taking on a big X
documentation rationalization project.  Cool!  It's
definitely something that needs to be done.

The hard part for us to decide is whether XCB should track
the new or old documentation for any given extension; I hope
we agree that it should slavishly follow one or the
other. :-) I know that for some extensions, there's little
or no published documentation at all; in those cases at
least it's clear that the XML description should follow your
docs.

While the core protocol documentation, for example, is not
"holy writ", it's something that's widely available to many
people and is largely OK.  I'd hate to see the XML diverge
there, and in fact I'd hate to see the names, etc in the
protocol documentation change without some kind of community
discussion first.

I'm really psyched that you want to take the lead in hosing
out this particular Augean Stable.  Just please do let us
help, and keep us and the rest of the community involved in
the decision making.

	Bart

In message <44186E22.3030404 at atoker.com> you wrote:
> Jeremy A. Kolb wrote:
> > onnoff is the name given in the headers,  Since we want to be true to the 
> > protocol shouldn't this name remain unchanged?
> 
> Quoting the original xv protocol spec:
> 
>      SelectVideoNotify
>        drawable: DRAWABLE
>        onoff: BOOL
> 
>      The SelectVideoNotify request enables or disables VideoNotify
>      event delivery to the requesting client.  VideoNotify events are
>      generated when video starts and stops.
> 
> You will notice that onoff is a boolean that will enable or disable the 
> delivery of the VideoNotify event.
> 
> I have issues with the semantics of "onoff". If "onoff" is TRUE, does 
> that mean it is both 'on' and 'off'? I don't think so.
> 
> While the X protocol specs are generally quite accurate, they are no 
> "holy book". In this case, it seems clear that "enable" or "enabled" is 
> an accurate description of the field while "onoff" is not.
> 
> In creating the 'xspec' branch, I've effectively offered to maintain the 
> X11 protocol docs, which are currently not provided in any standard 
> format. Some are written in troff, others in formatted text, some appear 
> to have been authored at some point with FrameMaker and others are not 
> documented anywhere except in the implementation, or the implementation 
> has long since deviated from the documentation.
> 
> The goal of xspec is to integrate this documentation in a standard XML 
> format, updating inconsistencies and adding cross-references in a 
> language-agnostic manner. Whether it will gain acceptance is another 
> matter, and it's quite possible that I might misinterpret a request here 
> or an event there, so your careful attention to every commit is welcome, 
> but I've stated my intention not only to annotate, but also to clarify 
> the documentation and hope you'll agree that this can only help.
> 
> _______________________________________________
> Xcb mailing list
> Xcb at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/xcb