[Xcb] XCB documentation effort status update
michael+xcb at stapelberg.de
Tue Nov 29 12:20:11 PST 2011
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:
> 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
> - 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
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
> - 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:
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
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.
More information about the Xcb