On Fri, 2012-01-27 at 09:49 +0100, Tomeu Vizoso wrote: > On Sat, Jan 14, 2012 at 23:30, Colin Walters <walt...@verbum.org> wrote: > > On Fri, 2012-01-13 at 14:17 +0100, Tomeu Vizoso wrote: > >> Hi, > >> > >> in a bit less than a month from now there will be a hackfest on > >> documentation in Brno [0]. Has anybody done any further work since > >> Berlin in generating API documentation in the Mallard format from the > >> GIR files? > > > > I don't think so...I'm not sure what state the work is in. Probably the > > first TODO item is to generate a TODO =) It's really great to hear > > you're looking at this! > > Shaun, do you have anything to say about this branch? > > http://git.gnome.org/browse/gobject-introspection/log/?h=mallard-templates > > Is it the way to go in your opinion or should we make a change in the > direction?
I do think it's the right direction, and I was happy with how it was panning out when I last worked on it. It just needs more work to get it producing really great docs. I did do work in tandem with this on an API reference extension to Mallard that allowed, for example, automatic links to be formatted as synopses. And with the conditional processing work I've been doing, it's possible to write for multiple programming languages in a single source file. The real problem with the whole concept is that the gtk-doc docs are written with the assumption that books are going to be made out of them. Whenever you have topics extracted from books, you're bound to have less than optimal results. For example, we only get docs for things like functions and signals, not the docs attached to the top of a C file. To gtk-doc, a single C file is basically a section in a book, and that section can have introductory material before the various reference subsections. To get top-notch docs for all bindings, I think we need to dogfood this with our C docs. That means removing "section" docs, moving conceptual information into separate pages, and writing with the assumption that references will be paged into topics that will be automatically converted for bindings. -- Shaun _______________________________________________ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list