new kde-examples module

[Friedrich W. H. Kossebau]

Mercredi, le 2 septembre 2009, à 14:30, Aaron J. Seigo a écrit:
> On September 2, 2009, Friedrich W. H. Kossebau wrote:
> > In general a good idea. :)
> >
> :)
> :
> > * Will it be a good idea to mix all examples for all the different
> > products of KDE?
>
> i think so; this gives people a "one stop shopping experience" for example
> code. it also means if someone is interested in, say, Phonon they will be
> more likely to grab all the other examples in one big package and by doing
> so be exposed to more of our wonderful work.

Try to really think as customer of KDE products:
Do you really want to be exposed to _all_ of the stuff (and get 
lost/distracted) if you just cared for a special thing?
If I want to work on Phonon I do not want or care for examples for Kate 
scripts, Umbrello exporters, KStyles, etc. that moment.
Instead I would be annoyed if I have to download/install all of that. I want 
to cherry pick. Like I want to just install Ark, and not have to coinstall 
Okteta just because it is also a cool program from kdeutils and I might have 
a use for it sometime ;)

This approach of "Oh, and you will be interested in all of the rest from us, 
too" is the view of the producer, who with some hope is in best believe of 
all his products. But at least I as customer am annoyed. And in my experience 
many others, too.

In fact, I believe packagers will split up these module anyway.

> knowing how people tend to work, it'll be common for someone to look for
> just one topic at first, then later a different topic. if we make them run
> around our source packages hunting it would be pretty annoying for them.
>
> > There is the workspace, there are standalone programs, there is the Dev
> > Platform, there is kdesupport (and more?). To get people into getting the
> > idea that KDE != "just the desktop environment" examples might be better
> > split and live near the products they are for (e.g. kipi-plugin examples
> > in extragear/graphics/kipi-plugins/examples and kioslave examples in
> > kdelibs/examples/kioslave), i.e. in the same module.
>
> this is -exactly- the situation we have now. and it sucks: people do not
> find our examples on their own. how do i know? because i'm constantly
> referring people to them ;)

No, not exactly the situation, because there is no simple pattern for 
organizing the examples (which is what I propose as alternative), it's all 
chaotic.

If we would go with $module/examples/$product/... the referrer and thing to 
memorize is also a oneliner.

> what makes this even worse is that most people who code with KDE libraries
> do not have our sources on their disk. they use binary packages. hunting in
> our sources is just not convenient in the least for most of our 3rd party
> developers.

The buildsystem can support the packagers to extract the example code, like it 
can with the headers for the devel packages, no?

> > * What about example plugins which rely on private (and with hidden
> > symbols) API?
>
> then they either need to provide copies of these classes in the examples
> module or not join the examples module. and, i would suggest, that if you
> design your library properly this is not necessary. people should not need
> (or want!) to use private bits in their app code.

I meant plugins :) 

> > codebase. For Okteta I started (not yet commited) to add example subdirs
> > with template/example files to dirs with pluggable systems and compile
> > these files to static libs, based on a set Makefile flag.
>
> could these same static libs live in examples/? if not, then Okteta's libs
> aren't ready for broad use yet and it's ok for them not to be in examples
> for the time being.

In Okteta's case there is no runtime plugin loading implemented yet 
(all "plugins" are hardcoded, due to moving API), just all the things like 
import/export/filter/checksum/filter/tools/whatever can get easily new 
variants by simply creating new subclasses and adding another instance in the 
code. Just, 3-party developers have a hard time to get into the structure of 
a complex program like Okteta, so giving them simple template code to start 
with will help.
I guess other programs/libs with unstable API could have similar needs.
So, at least Okteta could not make use of such a central approach for 
examples.

> > * How to ensure that the examples do not bitrot?
>
> they already do bitrot. so this would not be a new problem. i do have a
> hunch, though, that if more people were actually using the examples we'd
> hear about breakage sooner.

They already bitrotting is simply not acceptable IMHO. And forcing us to keep 
them up-to-date with the in-module placement (and breaking the build if 
broken, so getting the care they need) for me is a really big argument.
This could also be coupled with the API dox example snippets which could be 
outsourced to files and check compiled along with the example code.

> > While I agree it is a very good idea to improve visibility of example
> > code it should not be collected at one central place, but instead at
> > dedicated places inside each module, comparable to how the manuals are
> > organized.
>
> see above for why this simply doesn't work. we can certainly divide things
> up within an examples/ module, though.

I think I will work. Even better than with a single, isolated module only a 
few care for.

> > This would also help with versioning of the examples (and the API they
> > are based on).
>
> see Kevin's email for this.

At least helps with versioning of the main module examples. But what about all 
the stuff in extragear? Shouldn't there be just one simple and global 
solution?

Really, I think a KDE/kde-examples module looks more simple than it is. And 
given the transistion to git and the reorganisation, would it survive this?

Cheers
Friedrich
-- 
Okteta - KDE 4 Hex Editor - http://utils.kde.org/projects/okteta