splitting off bindings [was: Re: patch to TODO]

[Matthew Johnson]

On Wed, 15 Feb 2006, Havoc Pennington wrote:

> Hrm, another problem is docs; right now the glib bindings are in the
> same Doxygen module as libdbus I think (?), and the tutorial skeleton
> covers all the bindings at once.

Well, it covers them all sequentially, which I think could easily be
split off into separate modules, however see below....

> I _would_ like to avoid a "lowlevel only" tutorial as I think
> tutorial-type materials should strongly encourage use of a binding.
> The lowlevel API is, well, lowlevel, and if we encourage people to
> start there they are going to end up whining about its lowlevelness.

However, to throw in the other side of the argument, when people clearly
do want to use the low level API (which position I was in), there does
need to be a tutorial of how to do it. It took me so much longer than it
ought to have done to write what turned out to be reasonably simple
code. Hence why I wrote such a tutorial, people shouldn't have to dig
through the doxygen function list trying to work out which function they
need from cryptic descriptions. I should probably be more encouraging of
people to use other bindings if they possibly can at the top of it,
however.

> So it'd be cool if binding maintainers would maintain a section in the
> tutorial for their binding, or at least put a link in the tutorial to
> the canonical web location of their binding docs. (e.g. maybe the
> tutorial chapter on Qt just links to the right place on trolltech.com)

Either of these are fine, I think the bindings are still sufficiently
'part of DBus' that the docs can still be with the main tutorial.

> I think there's no need to move the broken/not-recently-maintained
> bindings, they could just be cvs rm'd and if someone comes along and
> decides to pick them up, they could go back in the history and get the
> old stuff.

Yeah, this is probably good to avoid people trying to use clearly broken
bindings. When people ask on IRC or the list and seem interested in
maintaining them, we can tell them to look at the history.

Matt
-- 
Matthew Johnson
http://www.matthew.ath.cx/