[Xcb] XCB documentation effort status update

[Michael Stapelberg]

Hi Alan,

Excerpts from Alan Coopersmith's message of 2011-11-29 08:04:56 +0000:
> Awesome progress!   I'll send a pull request on github with some typo fixes and
> improvements to the docs that I could make quickly myself.   Unfortunately, my
Thanks, merged your commits.

>   - A number of the man pages have pre-hyphenated words that don't match where
>       nroff/man needs to break, for instance, xcb_grab_button.3 outputs:
True. This is a sign of me copying over X documentation without carefully
looking :). Fixed it in a few occurences (everything that matched -$), so if
you still spot some mistakes, please point out where.

>   - RETURN VALUE for most of these is just going to be the cookie for getting
>       any reply or error code later.   Probably need either boilerplate or a
>       general xcb error handling page that all other pages point to and which
>       contains a more detailed introduction based on "Error handling Plan 7"
>       in libxcb/NEWS (and whereever else it got documented).
Yes. I plan to include a brief description on every page and a reference to
some manpage explaining the error handling in depth.

>   - ERRORS section currently looks like:
> 
> ERRORS
>       xcb_color_error_t
>                 The specified colormap cmap does not exist.
> 
>     But the actual error code returned (via the cookie lookup functions)
>     would be XCB_COLORMAP, with the details provided in a
>     xcb_colormap_error_t structure.
Hmm, yes. Good point. I think I’ll change that once the error handling manpage
is done. Since the section is auto-generated, it’s not a big deal to change
this.

>   - You should be able to get some useful details, such as why errors may be
>     generated, or definitions from the glossary, from the protocol spec at
>      http://www.x.org/releases/X11R7.6/doc/xproto/
Yes, I know this document and I’ve used it. In some occasions it does not
really describe the errors properly, though (or I’ve overlooked the relevant
sentences).

>   - xcb_change_gc - in the value_mask list, XCB_GC_LINE_STYLE refers to "Solid",
>     "DoubleDash", and "OnOffDash", but should use the enum xcb_line_style_t
>     names (XCB_LINE_STYLE_SOLID, etc.) - also, it looks like it wants table
>     formatting, but I guess that's not yet defined.  Same for the other
>     style enums (cap, bezel, join, fill, etc.)
> 
Yes, the documentation for xcb_change_gc is just copy&pasted without adapting
it a lot. Graphics contexts are a huge and confusing topic :-/.

>   - xcb_grab_button - For your question about "in the future", that's not a
>     reference to a planned change, but a reference to what happens in the
>     program after this call is made.
I see. I just removed the "In the future", since everything is going to happen
in the future (after the request was sent). Or is there some important nuance
I’m missing here?

>   - xcb_set_input_focus - the revert_to argument gives a list of values named
>     XCB_INPUT_FOCUS_*, then a bunch of text describing them with
>     XCB_REVERT_TO_* names instead.
Left-over of an old run, updated, see below.

>   - Some additional sources of sample code you may be able to borrow/adapt:
>     http://cgit.freedesktop.org/xorg/app/xwininfo/tree/
>     http://cgit.freedesktop.org/xorg/app/xlsatoms/tree/xlsatoms.c
>     http://cgit.freedesktop.org/xorg/app/xdpyinfo/commit/?id=072fc46b2af370e78fa53426626ca3c33b74bdf2
Good hint, thanks.

>   - Would you use XML entities or some other method to define repeated
>     information?   For instance, xcb_list_fonts, xcb_list_fonts_with_info,
>     xcb_open_font, etc. could all use a consistent explanation/pointer to
>     the XLFD doc for font pattern / name conventions.   And that doc may
>     be found locally (for instance, I package it for Solaris 11 in
>     /usr/share/doc/X11/specs/XLFD/ ) or it can be found online at
>     http://www.x.org/releases/X11R7.6/doc/xorg-docs/specs/XLFD/
Hm, I guess the online reference is more useful (since system-independent). I
would add that as another <see> tag for the SEE ALSO section. Do you agree or
did you have something very different in mind?

>   - If you'd like more help finishing, it would help to adopt a single way to
>     note unfinished bits - I've seen "blah blah", "TODO", and "NOT YET
>     DOCUMENTED" in various man pages.
Hm, "blah blah" was removed in the meantime, but I forgot to update the
pre-generated manpages. They are up-to-date now :). Also, I have prefixed the
"NOT YET DOCUMENTED" line (from the generator) with TODO (which was only in the
xml before), so that you can just grep for TODO.

Best regards,
Michael