[Xcb] XCB documentation effort

[Michael Stapelberg]

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.

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

Best regards,
Michael
-------------- next part --------------
A non-text attachment was scrubbed...
Name: xcb-manpage-generator.patch
Type: application/octet-stream
Size: 2266 bytes
Desc: not available
URL: <http://lists.freedesktop.org/archives/xcb/attachments/20111123/e40fd2e1/attachment.obj>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: xcb_map_window.3
Type: application/octet-stream
Size: 466 bytes
Desc: not available
URL: <http://lists.freedesktop.org/archives/xcb/attachments/20111123/e40fd2e1/attachment-0001.obj>