Tutorial notes

[Jeroen T. Vermeulen]

Hello,

I've been trying to work my way through the D-BUS Tutorial as a complete
newbie, though with some basic understanding of what it and systems like
it do (plus some experience with GLib, knowledge of Python, and a
conceptual overview of CORBA and such).  So far I've come across various
problems with the text that I've been asked to post here.

What follows is the list I have now.  It's not complete since I've
switched to reading the Specification instead, which is more
newbie-friendly.  I hope these notes will be useful in improving the text.

First off, some terms that are used before they are defined, are described
inadequately, or are never described at all:

 * Signal
 * Proxy
 * Service
 * Bus driver
 * Introspection XML file
 * Type signature

I _think_ I know what some of these mean, but I don't feel confident that
they don't have some more specific meaning in d-bus parlance.

Compare this to "objects:" by far most things in the tutorial that I would
call objects in programming practice are not objects in d-bus terms.  I'll
be using d-bus in Python, which has its own objects, but for that I gather
I'm expected to dive into glib as well, with its own, different and more
restrictive notion of an object.  So what, essentially, *is* an object as
the term is used here?  It's "an instance, not a type."  Thank you, that
part I knew.

The realization that something is really an object adds surprisingly
little quality to one's life.  The wonderful news that /everything/ is
really an object and can therefore interact with other objects is even
worse.  After that, the intimation that most things you'd consider objects
really aren't the kind of objects we've been calling objects is enough to
drive one to drink.  I'd have been much happier if objects had been
introduced as "communication endpoints" or "DService objects" or somesuch.
 As it is, I don't even have a word to set an object in the d-bus sense
apart from the other things called object!  At least glib has GObject.

Objects may be poorly named, but they're explained.  Not so for proxies:
the closest thing to an explanation of what proxies do (though not quite
their first mention) is in the first sample C program, where a proxy to a
bus is created.  There follows a paragraph called "Program initialization"
that describes this, but it's not made clear whether it describes general
practice or just the given example--are we *always* supposed to create a
proxy to a bus after connecting to it?  Or is that just what this example
happens to do?  If so, why?

The text directly after that is all about general practice, leaving the
reader with the impression that the bit about opening a proxy is general
practice as well.  So, since this is under Program Initialization, opening
a proxy on a connection is a standard part of program startup.  A proxy
must be a proxy "to the bus," something the program needs in order to
communicate with the bus, maybe something like an http proxy.  Later,
proxies to objects come as a complete surprise and invalidate everything
the reader thought he had understood.

While I'm at this point, that first example program is very poorly
documented!  There is no hint of what it's trying to achieve.  Remember,
this is an awfully long and complex program for the job it does, and it's
pretty hard to read for a first example--especially to readers not
familiar with glib.  It's also not a good showcase: "if this is what it
takes to write the simplest possible example, I may be better off without
d-bus.  How much more complexity before I actually get to *use* the bus?" 
Bear in mind that the reader does not know that this sample works by
sending messages, and that the bus object is just an example of an object
to talk to.

Also, there are only three lines of comments, two of them just rephrasing
the code instead of explaining it.  Perhaps after gotos, this style of
commenting is the first thing programming teachers hammer out of their
students--what's it doing here?

Then there is the question of "names."  The tutorial starts out by saying
that objects have names.  The comparison between names and pointers misses
the point entirely, IMHO; much better to use that wording to explain
proxies, and prepend an introduction to names.

But there is another problem: when names are introduced, there is no
mention of the fact that names are also given to a lot of other kinds of
objects (excuse me, entities).  Then later it turns out there are also
"bus names" which are described as "a property of the message bus daemon."
 I think the wording there is exceedingly unfortunate: "bus names" are,
from what we see further down, not names of buses.  Instead, they turn out
to be names of connections.

Calling these names "bus names" may not be exactly wrong (I'm trying to
think of an example, but the ones I've come up with so far turned out to
be much more sensible than this one).  Nor is "a property of the bus
daemon."  But read together, they seem to say that a bus name is a name of
a bus.  Why not simply start out by saying that every connection has a
unique name on the bus, that the application owning the connection can
request additional names for it that don't start with a colon, and that
all these names are called "a connection's bus names?"

On the point of glib: why go into a full list of glib type mappings before
the basic concepts have been explained?  Marshalling and structure haven't
even come up at this point.  For all the reader knows so far, a message
might be just a raw byte buffer.  Yet suddenly he's confronted with lists
of d-bus type signatures and what have you.

There are also some problems with the Python examples.  Several of them
refer to "bus.bus.get_object" which AFAICS should be just
"bus.get_object".

Also with the Python examples, under "Listening for Signals," it is
mentioned that "the" connect_to_signal method attaches a handler to a
proxy and takes a signal name and a handler as arguments.  That's nice,
but isn't the most important part that the signal handler attaches _to an
interface_ through "its" connect_to_signal method?  I don't see anything
about any relationship between signals and interfaces.  Could a signal
handler be attached to a proxy instead?

Finally, if you look at the SVG version of the overview picture, you'll
see an arrowhead pointing the wrong way.  You can't miss it: it's on the
left-hand side of the top box.  I've had that problem myself a few times
with older versions of some diagram editors.  The arrowhead points the
other way in the PNG version, as it probably should.

That's about it.  I realize I'm being difficult.  Then again, in my
experience one of the hardest things in the world is to take something you
already know and see it with the eyes of one who doesn't.  That's why I
hope a newbie's view can be useful.  I'd love to help write material for
the tutorial, but there's a chicken-and-egg problem: I don't think I have
enough of an understanding of the underlying concepts.  It's coming,
though, so hopefully I'll be able to contribute more constructively in the
future.


Jeroen