On 18 February 2012 07:47, Tomeu Vizoso <[email protected]> wrote: > ...snip... > We started generating DocBook from GIR files, trying to mimic GTK-Doc > as much as possible. Progress was slow and we had quite some problems > trying to rescue the DocBook that is embedded in the C sources. > > Shaun had already been working on using Mallard for the GNOME API docs > and at the g-i hackfest last year he quickly hacked up the initial > g-ir-doc-tool to output Mallard. Because it is higher level than > DocBook and because the yelp tools already had some support for API > references, it looked much more advanced than the DocBook generator > and it was clear to us that Mallard could do the job just fine.
Allow me to be frank; I don't see reasons other than academics to have an intermediate format. GIR is quite simple and suitable for being its own "intermediate format" already I think. Going straight to HTML (or something else) is so much more easier and opens the doors for the 99% of the developer community who doesn't know docbook, Mallard, or whatever we use. > When I was first told of Giraffe about a year ago, it was presented as > a stop-gap for generating HTML for Python API docs from GIR files. > Canonical had decided that they needed something quickly and had no > time to work with us in something that would fit GNOME's needs in the > longer term. Have just given a look at the code in the Giraffe > repository [1] and it indeed looks to me like something temporal, the > shortest line between A and B without regards to other needs that we > have, namely eventually replacing GTK-Doc and having more than one > output format. Let me chime in here, as the guilty party behind giraffe :-) Indeed, I threw giraffe together because at the time there was no way to generate docs for introspected languages. There were a few wip projects around, but after trying I couldn't really get any of them to work. It is true that the nature of giraffe was somewhat temporal, but I must also stress that I took some care to write it in a way that someone could pick it up and make it a complete solution. So yes, it is a minimal solution, but not necessarily where the road ends. Let me also clarify that giraffe certainly supports more than one output format. Currently it supports C and Python docs in HTML; but one could easily add any form of output (Mallard, or what ever floats your boat). Personally I want to add Vala and Seed/Gjs output (in HTML), but have never gotten around to it. > You mention reusing Giraffe's GIR parser, there's already a GIR parser > and an AST in GObject-Introspection that is mature, in use and being > maintained, why not reuse it and share the maintenance cost? I looked at the ast in gobject-introspection before starting giraffe. It didn't look like something that was intended as public API (nor do I think that would be a good idea). Also it did not look designed for generating documentation. Since GIR is a relatively simple XML format I decided to do my own thing. After all parsing XML in Python is not exactly rocket surgery; so the maintenance overhead of a multi-purpose public API didn't seem worthwhile for anyone. This also allowed me to expose a more DOM-like API tailored specifically for doc generation. Also - giraffe's AST is also mature and maintained - It's been running in production for over a year :-) Cheers, Mikkel _______________________________________________ desktop-devel-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/desktop-devel-list
