Until this patch is applied (if indeed it is ever applied - I'm not convinced it's correct at all), whatever project needs it (NetworkManager, I assume?) should preprocess its introspect++ XML to remove the extensions, and feed the preprocessed version rather than the hand-maintained version to dbus-binding-tool.

In Telepathy we have a different augmented introspect format, and some simple xsltproc+sed magic[0] that "un-augments" it. See tools/spec-to-introspect.xsl  and the top-level Makefile of recent telepathy-spec versions in http://telepathy.freedesktop.org/releases/telepathy-spec/ (or our Darcs repository).

[0] the sed command is necessary to get rid of the xmlns attribute for validation against the DTD, but could probably be made unnecessary by using better XSLT: <xsl:stylesheet exclude-result-prefixes="tp"> might work

Created attachment 15088 [details] [review]
Ignore namespaced nodes/attributes _and_ don't fail on unknown elements below those nodes

The reason we're not using the telepathy process is precisely because we don't want an additional level of indirection here.  Second, we do not want to _require_ that the documentation be built to get the introspection XML out.  But of course the introspection source and the authoritative documentation source should be in the same place.

With the TP style, it's Spec -> [introspection XML -> glue, HTML]; which I see as an unnecessary intermediate step.  There's no reason you can't have introspection XML -> [HTML, glue].  Otherwise it's just pointless abstraction.

Besides, the only reason dbus-binding tool doesn't handle this case is because it doesn't actually handle XML; it just parses the format without any knowledge of the meaning of the attributes.  That is, of course, wrong.

The problem with this patch is that when Introspect() is called, the namespaced
additions will be sent over the wire, and not all bindings know about
namespaces.
It also probably not right to send documentation over the wire anyhow ;)

It would be good to get a cross-binding agreement about namespaced additions,
but until this happens, its best to strip out any namespaces your application
has added before passing to dbus-glib.

So at a high level, the introspection XML was originally supposed to be a temporary hack until we got GObject introspection.  So I think we should keep in mind how any features added to the system would apply in terms of introspection.  In this particular case of documentation you could imagine that tools like gtk-doc would understand how to work with exported GObjects.

However, we have to be realistic and consider that until GObject introspection lands, projects are going to want the ability to add things like this.  

I understand Simon's desire to leave the introspection format as-is and define a new format, but at the same time I don't see the problem with improving dbus-binding-tool if it makes the build process more convenient.

I think it is useful to have more centralization of build processes; having everyone copy+paste some XSLT goes against that.

Rob - in fact these namespaced additions will not be sent over the wire.  Remember dbus-binding-tool parses the XML at build time to generate structures, which it then uses at runtime; including re-generating new XML from those structures.  Because the namespaced additions are not included in the structures, they will not be in the XML received by other programs.

(please consider the patch, +1 from me)

Ah, ok my bad! This is now committed on master in patch  bd53ac9f7ef9a6c2c9d1d12af382b1a8a10e9dba.

Colin, you'll be glad to hear that we've been making a lot of progress on gobject-introspection, expect some blog posts soon.. Its my only excuse for having forgotten half the codebase of dbus-glib ;)