Fwd: Re: Annotation in introspection XML <arg> elements?

[Lennart Poettering]

On Tue, 11.11.14 11:59, Simon McVittie (simon.mcvittie at collabora.co.uk) wrote:

> On 10/11/14 21:29, Lennart Poettering wrote:
> > http://standards.freedesktop.org/dbus/1.0/introspect.dtd
> >
> > That said, the spec uses this in the doctype:
> >
> > http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd
> >
> > Which redirects to the first link.
> >
> > Which brings us to another question, what should the dbus spec
> > reference in the doctype there? The URL or the new one?
> 
> Has anyone ever validated introspection XML against a DTD, except as a
> stick with which to beat implementations that are in some way
> pedantically non-compliant?
> 
> (In case it isn't obvious, I don't think the DTD is particularly useful;
> reading the spec text is necessary to understand the semantics anyway,
> and the semantics are the thing that matters.)

Well, the spec isn't particularly precise when it comes to a
description of the introspection format. The DTD has the benefit that
it is quite formal, and still reasonably easy to read. Given that
shortcomings of the spec in this area I think the DTD has quite some
value.

> The main roles of introspection XML seem to be:
> 
> * a simple IDL used by code generators
> * misleading people who don't understand D-Bus into thinking it's
>   some XML-based protocol like XMLRPC or SOAP
> * "documentation" for tools like d-feet

I think it has the benefit of making D-Bus a bit more accessible
through the introspection tools. For example I yesterday added support
for dumping object trees to stdout to systemd's busctl tool. THis is
similar in style to what D-Bus does. I am pretty sure we have the duty
to make D-Bus a bit more transparent for admin folks to grok.

Back in Avahi I actually shipped the XML introspection data in
external files, verified them at build time against the DTD and
shipped an XSLT styesheet so that you could look at them in a
browser. In that context it kinda made sense to me I must say.

Lennart

-- 
Lennart Poettering, Red Hat