[Xcb] Branch 'xspec' - xcb-proto

[Ian Osgood]

My two cents:

I've also been changing the names of constants as I move them from  
X.h to xproto.xml.

  BadRequest   --> XCBRequest (should be XCBBadRequest or  
XCBRequestError?)
  ShiftMask    --> XCBModMaskShift
  Mod1Mask     --> XCBModMask1
  Button1Mask  --> XCBButtonMask1
  InputOutput  --> XCBWindowClassInputOutput
  WhenMapped   --> XCBBackingStoreWhenMapped
  KeyPressMask --> XCBEventMaskKeyPress
  IsViewable   --> XCBMapStateViewable
  CWX          --> XCBConfigWindowX
  LineSolid    --> XCBLineStyleSolid
  CapButt      --> XCBCapStyleButt
  JoinRound    --> XCBJoinStyleRound
  FillTile     --> XCBFillStyleTile
  WindingRule  --> XCBFillRuleWinding
  XYBitmap     --> XCBImageFormatXYBitmap  (should be  
XCBImageFormatBitmap?)
  LSBFirst     --> XCBImageOrderLSBFirst

This is due mainly to the naming conventions enforced by <enum>.  The  
prefixes also help relate the enumerations to the requests, fields,  
or settings to which they apply.  I haven't heard anyone object so  
far.  (That usually means that nobody noticed or no one cares.)

We also apparently need more enumerations. I've seen lots of code in  
xcb-util and xcb-demo with parameters like

   ... 0, /* some meaning */ ...

which should of course be a named constant.

(Is the protocol spec only widely available in hard-copy? Can you  
point me to the web pages which describe the core protocol and de- 
facto standard extensions?)

I also find Alp's renaming welcome. I'm coming at this as a Windows  
and Mac developer. They each have excellent online API references and  
(mostly) consistent naming conventions.  Perhaps a meta-spec is in  
order to outline conventions to be used in the new protocol specs?

Ian

On Mar 15, 2006, at 4:08 PM, Barton C Massey wrote:

> 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
> _______________________________________________
> Xcb mailing list
> Xcb at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/xcb
>