new kde-examples module

[Friedrich W. H. Kossebau]

Mercredi., le 2 septembre 2009, à 13:17, Aaron J. Seigo a écrit:
> hello everyone ..
>
> i am creating a new module that will sit in trunk/ called kde-examples. the
> point of this module will be to collect all of our small example apps into
> one place.
>
> this will:
>
> * make it easier for people to find as they will all be in one place
>
> * make it easy to ship as it will be distilled out of kdelibs and other
> modules
>
> * make a great pairing for our generated developer documentation
>
> the module would not be shipped as part of KDE Software Distribution
> releases, but would be made available for download as a source package
> from, e.g., techbase.
>
> if there are any objections to this plan, please speak now before i do more
> work.

In general a good idea. :)

Just:
* Will it be a good idea to mix all examples for all the different products of 
KDE?
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.

* What about example plugins which rely on private (and with hidden symbols) 
API?
Those might have a hard time living and being compiled outside their home 
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.

* How to ensure that the examples do not bitrot?
Given how few are running the tests I fear that noone will "cd kde-examples" 
and compile the appropriate examples for the code she just changed. If the 
examples would instead be inside the module, and by default (my vote) even in 
the dependency chain of the build system, they will always be up-to-date. 
Which will be very helpful to newbies. Broken examples are frustrating and 
give a bad impression.

So:
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. This would 
also help with versioning of the examples (and the API they are based on).

> (the addition of more examples in kdecore/auth/examples is what jogged my
> memory on this one :)

(It's example time? Just started to write examples for Okteta plugins last 
WE :)

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