[Xcb] XCB documentation effort status update

[Alan Coopersmith]

On 11/27/11 02:44, Michael Stapelberg wrote:
> Status update: I "completed" documentation on 32 functions. With complete I
> mean that there is some kind of explanation for all parameters, a description,
> a list of possible errors and a 'see also' section. In some places, there are
> still TODO entries for missing high-level or detail explanations. Help is
> appreciated!
>
> I created the following three repositories on github:
> 1) https://github.com/mstap/xcb-man-pregenerated
>     Pregenerated manpages for easier reviewing.
> Proofreading, comments, suggestions, etc. are very welcome.

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
python skills are non-existent so I can't help much on the generation side.

Some other review comments I don't have quick patches for:

  - 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:

      The interpretation of the remaining arguments is the same as
      for GrabPointer. The active grab is terminated automatically
      when the logical state of the pointer has all buttons
      released, indepen- dent of the logical state of modifier
      keys. Note that the logical state of a device (as seen by
      means of the protocol) may lag the physical state if device
      event processing is frozen.  This request overrides all pre-
      vious passive grabs by the same client on the same
      button/key com- binations on the same window. A modifier of

  - 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).

  - 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.

  - 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/

  - 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.)

  - 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.

  - 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.

  - 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

  - 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/

  - 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.

-- 
	-Alan Coopersmith-        alan.coopersmith at oracle.com
	 Oracle Solaris Platform Engineering: X Window System