[Xcb] XCB documentation effort
marcoz at osource.org
Tue Nov 22 11:16:37 PST 2011
On 11/21/2011 06:51 PM, Alan Coopersmith wrote:
> On 11/21/11 14:33, Michael Stapelberg wrote:
>> Hi everybody,
>> we just concluded in #i3 that XCB is poorly documented (no news here).
>> want to fix this. I’ll list a few random thoughts:
>> 1) The wiki could needs some love. Not sure if our primary focus
>> should be
>> on the wiki, though?
>> 2) We need manpages for functions, just like Xlib has them. We can
>> start by
>> just using the X11 protocol description for every request (automatically
>> generating that) and then enhance it with human-written
>> 3) The function documentation should probably end up in doxygen as
>> well, though
>> I’m not an experienced doxygen user.
>> Here are my questions to you:
>> 1) Is anyone *currently* *actively* working on documentation? If so,
>> your status/goals/timeline?
>> 2) Does anyone object to my thoughts above and if so, why?
>> 3) Did I miss anything that seems important?
>> 4) Do you have any hints/tips?
> Matt Dew has been working on the X documentation in general, especially
> finishing up our long planned transition of all the docs from a random
> collection of formats to be standardized in DocBook/XML, but I don't
> think he's looked much at XCB yet.
> I know there's some people who'd like to generate the X protocol specs that
> he has been helping with directly from the XCB - that seems very doable for
> the encoding sections, but the full text would be more challenging and not
> as useful as actually having all the XCB calls documented in a more direct
> way than "Go see the protocol specs."
I have not looked at XCB specifically. I actually think XCB is one of
the better documented areas of X so it wasn't high on my list. It has
more doxygen work done than any other area, except possibly the doxygen
work done on the input system done by Peter Hutterer.
To specifically answer your questions:
1) Yes, I'm actively working on documentation. (though I'm not fast at
it, I only get a few hours a week to work on it.)
A) to convert all the intree documentation into docbook. - pretty
B) cleanup and style those docs into a set so it looks really nice.
- end of year
C) Update the documentation so it's accurate - no idea how long
this will take; hopefully by XDS 2012
D) re-organize the wiki - start on that Beginning of next year,
hopefully done by XDS 2012
2) +1 - if you can generate the manpages from doxygen, that's the best
IMHO. I'm still a newbie at doxygen though so I don't know the options here.
3) I think you need to have a discussion to determine what exactly
people think needs to be done and break it down into individual steps;
not necessarily a specific order, but at least what needs to be done. A
face-to-face meeting to start would be the best, with lots of whiteboard
space and take pictures of all the whiteboard drawings and record the
audio of the entire meeting(s).
Re-organizing a wiki is a _HUGE_ amount of work and it gets tedious
and boring really quickly. Don't underestimate it.
4) Keep as much documentation in the source code files as possible;
doxygen for what you can. It's the most maintainable long term. Having
to maintain documentation separately from the code is extra work and
it's very easy for them to diverge over time; you can pretty much be
guaranteed that they will diverge. Think carefully about what you want
on the wiki. Personally I don't think that wikis are not the best place
for a lot of documentation; unless you do it like gentoo where those
pages are generated from static xml files (which could be generated from
Example: If the config file doesn't change, don't put the documentation
for it in wiki form. Put it in the code, if possible, and generate the
man-pages and web-documentation from that. Then if someone references
it in a wiki page, just add a link to the generated documentation.
If possible, there needs to be a small group or team in charge of the
wiki, for consistency. Others can edit but allowing everyone to create
their own structure will result in no overarching theme; which makes it
harder to find things. "Too many chefs spoil the broth."
Ugly but consistent beats pretty but inconsistent.
Sorry for the essay there. These are just my humble opinions. I hope
Let me know if I can help.
P.S. Alan, the last of the docbook docs, Intrinsics in libXt, is
actually done. At this point I'm just using it for styling
experimentation to see what looks good. Then I'll use that to mark up
the other docs. If you're curious:
More information about the Xcb