DBus XML Documentation Parser

[Simon McVittie]

On Tue, 03 Jan 2017 at 15:34:55 -0000, Gary Partis wrote:
> I'd like to do the following to allow for text macros in dbus XML files
...
> 1. within the Dbus XML, have a   <macro name="foo" value="bah bah black
> sheep"/>   type settings for at the beginning of the <node> section.
...
> Does anyone have a problem with this?

You are defining a format that is not D-Bus introspection XML.
You are free to define such formats, but you can't expect tools that
expect D-Bus introspection XML to understand them, just like you can't
expect a standard C compiler to understand Objective-C or C++.

If your extensions are something that the D-Bus tools you are interested
in will ignore gracefully (for example elements in a different XML
namespace), then you can use your extended markup as-is (but you can't
expect generic D-Bus tools to extract any information from it).
For example, the Telepathy[1] specification is written in an extended form
of D-Bus introspection XML, which gets processed through some scripts to
produce HTML.

Please use your own XML namespace (for example
<partis:macro xmlns:partis="some URL you control"/>) when extending
someone else's XML format. Again, Telepathy does this correctly (with
the http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0
namespace, conventionally linked to the tp: prefix).

If your extensions change the semantics of the introspection XML,
for example supporting some sort of macro inside "signature" attributes,
then you can't treat it as introspection XML any more: generic tools would
give the wrong results for it. One way you could deal with this would be to
write D-Bus APIs in your own format based on D-Bus introspection XML,
process that format through some script to get valid D-Bus introspection XML
(for example expanding the macros), and use its output as the input for
D-Bus tools.

Regards,
    S

[1] https://telepathy.freedesktop.org/