Created attachment 53120 [details] [review]
make the required changes

Yes, that looks OK to me.

It would be nice if the new format added a version attribute to the root node or
something like that so that devhelp can know which tags to look for.

a different idea, wouldn't it be better to make .devhelp2 files with the new syntax?

Gtk-doc would get a configure option "--disable-devhelp1" or
"--disable-devhelp1-format". If given the stylesheets would be configured to not
produce the old format. This help distributors to keep the old files out, if the
ship a new devhelp that can read devhelp2 files.

Devhelp will always try devhelp2 files first and falls back to the old devhelp
files if there is no new one (yet).

Would that be better? Or should I just add a 'version="2"' attribute to the
top-level element.

I think making it output both the old and new format would make sense. I thought
that an old devhelp would be able to parse the new file since it has the old
function tag in it, but it turns out it bails out when it sees the new tag :/

We should also add a version tag to the new format anyway to make this kind of
change easier in the future.

Stefan, what do you think we should do here?

Richard, I've now commited the changes to produce two separate files.