[cairo] a note on docs

[Andy Wingo]

Hey all,

I understand that there are movements or desires for changing how cairo
documentation works. Sounds good. The existing reference lacks context;
I don't think I would have learned without having seen Carl's
presentation in Vilanova last year).

It would be great if any new system ensures that the function-level
documentation is available for programmatic consumption. I was able to
put together some pretty decent docs[0] for a language binding[1] based
on munging the docbook produced by gtk-doc; I understand that at least
the haskell and gtkmm people do similar things, although not necessarily
with their cairo wrappers.

Specific useful aspects of the gtk-doc documentation are:

  (1) the hand-ordering of function documentations, instead of
      alphabetical/some other automatic scheme;
  (2) grouping of function documentations into sections (cairo_t,
      paths, etc), and order within the sections; and
  (3) section documentation in a mungeable format (docbook in the
      current case).

Docbook is a more or less good format, programmatically, although as
employed by gtk-doc it is not ideal as a primary source. HTML could be
fine (potentally as an intermediate format, e.g. after markdown) if it
were used as a semantic (and not presentational) markup, with strong
conventions about how functions, return values, and arguments are
marked.