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

[Barton C Massey]

The only issue is that we'd like the names in XCB to reflect
the names in some well-recognized and complete standards
document.  Otherwise we have to make up and document our own
names for everything, which is a royal pain, or risk
confusion about what naming scheme applies for each name in
the X language bindings.

Once Alp's document has progressed to the point where it can
be treated as such a standard, we'll be quite pleased to
move to his assuredly more rational names.  In the meantime,
I think the Xorg docs provide the only accepted naming
standard we have.  (I agree that the Xlib headers are not a
good choice here, although we may have used them sometimes
when we shouldn't have.)

Let me be 100% clear---I think the task Alp has volunteered
for is a truly heroic one, and I wish him every success.
Rationalizing this documentation has been needed for a
really long time.

Hope that clarifies the situation a bit.

	Bart

In message <F0EF955E-FBDE-4C51-84E9-ED24A60687CC at mac.com> you wrote:
> Hi!
> 
> I just want to say that you, Alp, are totally on the correct track  
> and renaming something like that is the Right Way™ IMHO.
> 
> I'm not sure why everyone has jumped about this. As you noted in a  
> previous e-mail, "onoff" (the string) /never/ crosses the wire, so  
> renaming it has Not One Thing At All In The World To Do With The X  
> Wire Protocol™. It will only ever be read by a developer. A  
> difference in capitalization will, likely, not even be noticed. A  
> difference between "onoff" and "enabled" will only make the developer  
> prefer your documentation over another. That, it seems, is a good thing!
> 
> On the other hand, if XCB wants to keep its existing, stable,  
> released API... wait, there hasn't been a release. Oh, so there's no  
> problem then? :-)
> 
> Just my $0.02, feel free to ignore me.
> 
> JP
> 
> On 15 Mar 2006, at 11:42, Alp Toker 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
> 
> _______________________________________________
> Xcb mailing list
> Xcb at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/xcb