Thoughts on documentation

[Andy Wingo]

Hi all,

At FOSDEM this year, there was a suggestion, from the maintainer of the
haskell-gtk bindings iirc, that we use the devhelp documentation index
to automatically generate documentation for our wrapper libraries. This
seems to me to be a fine idea. Devhelp files (see e.g. on
debian /usr/share/doc/libgtk2.0-doc/gtk/gtk.devhelp2.gz) are basically
an index to a set of HTML documents. We can parse these with SSAX and
somehow fold the documentation into the files generated at compile-time,
perhaps translating the HTML subset that they use into the S-texinfo
representation that guile-lib defines. We can also perform certain
canonical transformations, e.g. gtk_bin_add -> gtk-bin-add, and use
information about arguments to transform e.g. gtk_icon_size_lookup(size,
*x, *y) to document the fact that it returns multiple values (as it
does).

We might need to hack the help system a bit so we can make all of this
information available at runtime without actually loading it all into
memory, but that is doable.

I just wanted to write because I had a brain wave, and wanted any
comments or ideas before implementing it :)

Cheers,

Andy.
-- 
http://wingolog.org/