[Xcb] XCB documentation effort

[Michael Stapelberg]

Hi Peter,

Excerpts from Peter Harris's message of 2011-11-24 17:07:15 +0000:
> - The man pages include proto names instead of xcb names (eg. See also:
> MapWindow(3)). You're probably going to want to mangle those in
> c_client.py so that "man <copy-and-paste>" actually works.
Yes, I’ve fixed that now.

> - The names in xproto.xml are case sensitive. There is an error
> described in the document named "Window", but not "WINDOW". This should
> be fixed (at the very least, it may confuse the name mangling. See
> previous point). Of lesser importance, <error name=""> would be more
> consistent than <error type="">.
Thanks, I’ve changed that.

> - You haven't updated src/xcb.xsd yet, so "make check" in xcb/proto
> fails. You're still fleshing out what you want, so I don't expect this
> to be done yet. I just mention it so it doesn't fall off your TO DO
> list. On a related note, doc/xml-xcb.txt also needs to be updated,
> eventually.
Right. I’ll postpone that until I’m confident that the XML format doesn’t need
any changes.

Status update:

I documented a few more requests and improved the generation part (which only
handles requests right now): The reply function, data structure and accessor
functions are now also included (in separate sections to not clutter the
SYNOPSIS too much).

I have attached a few fairly well documented examples so that you can get an
impression. I am happy to receive comments/suggestions/improvements.

I also have a few questions:

1) Take the CreateGC request:
   <request name="CreateGC" opcode="55">
     <pad bytes="1" />
     <field type="GCONTEXT" name="cid" />
     <field type="DRAWABLE" name="drawable" />
     <valueparam value-mask-type="CARD32"
                 value-mask-name="value_mask"
                 value-list-name="value_list" />
   </request>

   It obviously supports a bitmask plus some values, which are defined in the
   enum GC:
   <enum name="GC">
     <item name="Function">          <bit>0</bit></item>
     …
   </enum>

   Now my question is: Where is the connection? How can my generator know what
   appropriate values for value_mask are?

2) Instead of using one-letter variable names like 'c' for connection or 'R'
   for reply, I would like to use 'conn' for connection and 'reply'. Do you
   have a strong opinion about keeping them one-letter names or can I change
   them (in the documentation only)?


Best regards,
Michael
-------------- next part --------------
A non-text attachment was scrubbed...
Name: libxcb.patch
Type: application/octet-stream
Size: 12870 bytes
Desc: not available
URL: <http://lists.freedesktop.org/archives/xcb/attachments/20111124/25903c7b/attachment-0013.obj>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: xcb-proto.patch
Type: application/octet-stream
Size: 18264 bytes
Desc: not available
URL: <http://lists.freedesktop.org/archives/xcb/attachments/20111124/25903c7b/attachment-0014.obj>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: xcb_warp_pointer.3
Type: application/octet-stream
Size: 2333 bytes
Desc: not available
URL: <http://lists.freedesktop.org/archives/xcb/attachments/20111124/25903c7b/attachment-0015.obj>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: xcb_get_selection_owner.3
Type: application/octet-stream
Size: 1312 bytes
Desc: not available
URL: <http://lists.freedesktop.org/archives/xcb/attachments/20111124/25903c7b/attachment-0016.obj>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: xcb_get_property.3
Type: application/octet-stream
Size: 3844 bytes
Desc: not available
URL: <http://lists.freedesktop.org/archives/xcb/attachments/20111124/25903c7b/attachment-0017.obj>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: xcb_intern_atom.3
Type: application/octet-stream
Size: 2154 bytes
Desc: not available
URL: <http://lists.freedesktop.org/archives/xcb/attachments/20111124/25903c7b/attachment-0018.obj>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: xcb_get_geometry.3
Type: application/octet-stream
Size: 1973 bytes
Desc: not available
URL: <http://lists.freedesktop.org/archives/xcb/attachments/20111124/25903c7b/attachment-0019.obj>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: xcb_configure_window.3
Type: application/octet-stream
Size: 1768 bytes
Desc: not available
URL: <http://lists.freedesktop.org/archives/xcb/attachments/20111124/25903c7b/attachment-0020.obj>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: xcb_unmap_window.3
Type: application/octet-stream
Size: 992 bytes
Desc: not available
URL: <http://lists.freedesktop.org/archives/xcb/attachments/20111124/25903c7b/attachment-0021.obj>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: xcb_map_window.3
Type: application/octet-stream
Size: 1658 bytes
Desc: not available
URL: <http://lists.freedesktop.org/archives/xcb/attachments/20111124/25903c7b/attachment-0022.obj>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: xcb_reparent_window.3
Type: application/octet-stream
Size: 1688 bytes
Desc: not available
URL: <http://lists.freedesktop.org/archives/xcb/attachments/20111124/25903c7b/attachment-0023.obj>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: xcb_change_save_set.3
Type: application/octet-stream
Size: 1226 bytes
Desc: not available
URL: <http://lists.freedesktop.org/archives/xcb/attachments/20111124/25903c7b/attachment-0024.obj>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: xcb_destroy_window.3
Type: application/octet-stream
Size: 1075 bytes
Desc: not available
URL: <http://lists.freedesktop.org/archives/xcb/attachments/20111124/25903c7b/attachment-0025.obj>