[Xcb] XCB documentation effort

[Josh Triplett]

On Wed, Nov 23, 2011 at 08:18:28PM +0000, Michael Stapelberg wrote:
> Hi again,
> 
> Excerpts from Michael Stapelberg's message of 2011-11-22 21:45:37 +0000:
> > The following things bother me with this manpage:
> > [... explanations on why doxygen’s manpage output is not good enough ...]
> I think the best solution for this problem is to not generate C code which is
> then ran through another generator (doxygen), but rather generate manpages
> directly when generating the C code. This has the advantages that we have full
> control over the output format and filenames. Also, we do not introduce any new
> dependencies (we wouldn’t when using doxygen either, just saying).
> 
> Any objections? A patch on how this currently looks is attached (obviously this
> is not the best solution and should probably be refactored in some way. Also,
> it only handles requests at the moment, but hey, it’s a proof of concept :).
> 
> The result is also attached (xcb_map_window.3). Looks a lot better than its
> doxygen equivalent, IMO.

Very nice.  Generating manpages directly seems reasonable to me, and the
template you've started with looks good.

I assume the final version will write to the final manpages directly,
rather than to an insecure temporary file with an easily predicted name?
:)

> > 2) Is the modification of xproto.xml OK with you? I decided to go for a <doc>
> >    tag because it can then have sections for the individual fields and errors
> >    and whatever else we will stumble upon. I used the <description> tag to be
> >    able to use CDATA, which does not seem to be possible with XML attributes.
> >    Patches are attached.
> This one still stands.

Seems fine to me.  I agree with the use of a tag rather than an
attribute; embedding a pile of documentation in a single XML attribute
seems crazy.

- Josh Triplett