'What is D-Bus' introductory document

[Lawrence D'Oliveiro]

On Sun, 23 Jan 2022 18:32:49 +0000, Thomas Kluyver wrote:

> You can see the result at:
> https://jeepney--28.org.readthedocs.build/en/28/dbus-background.html

Good to have an intro. A few things that come immediately to mind:

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.

Under the “Message buses” section, which begins “Applications using
D-Bus connect to a message bus, a small program which is always
running. The bus takes care of delivering messages to other
applications”: worth adding something like

    Bus connections are uniquely identified on a message bus by a _bus
    name_. A bus name can be a _well-known name_, chosen by the
    registering application, which other applications can use to request
    services from this one. A bus connection can register
    multiple well-known names. Regardless of whether a connection
    registers any well-known names or not, it always has a _unique
    name_, which is used to address replies to method calls. This way,
    client applications can request services without having to register
    their own well-known names.

(Maybe that’s too much, and should be cut down in the introductory
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.

In the Names section, you don’t mention method names. Also, how about
the fact that method calls are basically strongly typed?

> I've deliberately left out a lot of information that could be there -
> e.g. about transports, authentication, data types, or introspection -
> because I want to keep it as concise as possible, and to focus on
> what you could do with D-Bus, not how it works.

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