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

[John Davidorff Pell]

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