'What is D-Bus' introductory document

[Thomas Kluyver]

Thanks Lawrence,

On Sun, 23 Jan 2022, at 19:58, Lawrence D'Oliveiro wrote:
> In the first sentence, worth mentioning that D-Bus is “high-level”.
> E.g. “D-Bus is a high-level system for programs on the same computer to
> communicate.” This is to indicate that it deals with transmitting
> data structures made out of various predefined pieces, not arbitrary
> byte streams.

I think the example makes it clear that D-Bus is based around messages rather than streams. The fact that D-Bus defines a particular structure for messages, and that they're strongly typed, is getting into details that I don't think need to be here. If someone starts actually using D-Bus, this will become clear to them pretty quickly.

(I don't find 'high-level' a useful description. I agree that it's high-level compared to e.g. raw sockets, but from my perspective as a Python programmer, having to distinguish signed from unsigned integers feels like quite a low-level thing, i.e. closer to the workings of the machine. High- or low-level is only meaningful if you know what the reference point is, and I can't assume the target reader will.)

> Under the “Message buses” section...
>
> I see the next section talks about “Names”. But this section already
> mentions the name of the message bus itself, before you get to any
> explanation about names, which is why I think something about these
> should be added in the prior section.

This is a good point. The names section doesn't really mention message buses at all (except for the 'bus name', and they can read to the next section to understand that), so I think I can simply swap these two pieces round.

> In the Names section, you don’t mention method names.

I do! ;-)

"Finally, a simple name like Notify or NotificationClosed identifies which method is being called, or which signal is being sent..."

> Yes, this makes sense. But still perhaps worth mentioning standard
> interfaces for introspection and properties, at least, since these are
> such common needs.

I do briefly mention introspection (in the bullet point on the interface name). If people know it exists, I assume they can find elsewhere how to use it.

I find it hard to sum up the properties interface in a similar way without either assuming people are quite proficient programmers, or writing a sizeable paragraph to motivate why you want a special interface for that. So I think I have to consign that to the 'find it out when you need it' bucket.

Best wishes,
Thomas