Bug 104947

Summary:	Documentation tutorial
Product:	dbus	Reporter:	Dilian <dpa-bugs>
Component:	core	Assignee:	D-Bus Maintainers <dbus>
Status:	RESOLVED MOVED	QA Contact:	D-Bus Maintainers <dbus>
Severity:	normal
Priority:	medium	Keywords:	love
Version:	unspecified
Hardware:	Other
OS:	All
Whiteboard:
i915 platform:		i915 features:

Description Dilian 2018-02-05 10:23:40 UTC

This is an Introduction to DBus: https://www.freedesktop.org/wiki/IntroductionToDBus/

This is a Tutorial to DBus: https://dbus.freedesktop.org/doc/dbus-tutorial.html .

Together they are confusing and repeat each other.

The former
* shall contain a reference to the later,
* In Buses-section, 2nd paragraph, state that DCOP was used in KDE up to version 3
* In the Proxies-section I propose changing the beginning to "Objects on the other end on the bus can be accessed..." to be the opposite of the section in the Objects-section "One end of any exchange on a bus will always be a ... called an onject".  So at the end the documentation shall read "one end is object, other end is proxy", except I don't understood things correctly.
* Section 'Signals' first paragraph, third sentence. I propose inserting the work "proxy", so that it reads "Client processes (proxies)  can register an interest..." to make clear that a client process is the same as proxy.

Comment 1 Simon McVittie 2018-02-06 12:56:46 UTC

Contributions/concrete proposals are welcome. Sorry, I don't have the bandwidth at the moment to rewrite existing documentation, but if you propose changes, I can look at reviewing and merging those changes. I suspect the same is true for all the other maintainers.

The source code for https://www.freedesktop.org/wiki/IntroductionToDBus/ is viewable at https://cgit.freedesktop.org/wiki/www/ (git URLs to clone it can be seen at the bottom of that cgit page). It's written in ikiwiki's dialect of Markdown, possibly mechanically converted from an earlier wiki.

The source code for the tutorial is part of https://cgit.freedesktop.org/dbus/dbus/ alongside the reference implementation and the specification, although that isn't necessarily the place where it makes the most sense to keep it. It's written in Docbook XML.

It might make more sense to consolidate both the introduction and the tutorial into one place, and leave a stub page in the other location that just points to the consolidated version. Or it might not make sense - see below.

One major problem with the tutorial is that, for historical reasons, it describes libdbus, the reference C implementation of D-Bus. However, libdbus is no longer what we recommend people use, especially if they are new to D-Bus - it's low level and not very friendly. GDBus (C, in GLib), QtDBus (C++, in Qt) and sd-bus (C, in systemd) are better alternatives.

It might make more sense to have a centralized introduction to the D-Bus protocol and concepts (that is implementation-independent), but tutorials for specific D-Bus implementations (as part of each implementation's documentation). I think that's the direction that GDBus and QtDBus have gone in.

Comment 2 GitLab Migration User 2018-10-12 21:32:38 UTC

-- GitLab Migration Automatic Message --

This bug has been migrated to freedesktop.org's GitLab instance and has been closed from further activity.

You can subscribe and participate further through the new bug through this link to our GitLab instance: https://gitlab.freedesktop.org/dbus/dbus/issues/197.

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.