Proposal: new non-shipping module for examples

[Aaron J. Seigo]

On Friday 03 October 2008, Brad Hards wrote:
> On Friday 03 October 2008 12:46:16 pm Aaron J. Seigo wrote:
> > > I think the best approach is to ship it inside the module,
> >
> > so to get all kde examples you have to download the source of every
> > module with examples?
>
> If you have an external module and want to use all the examples (as opposed
> to "having" them), you'll probably need the source (or the -devel packages)
> of every module anyway. I don't think that this is all that common anyway -
> seems unlikely that most people aren't interested in "everything" - they
> have some focus (perhaps plasma or akonadi, libraries or accessibility,
> whatever) and would like the examples for that.

it's a great way to expose people to more topics, however; they may start out 
interested in plasma, but if they see those cool akonadi examples, well ... =)

this also makes it easy/clear for people putting together course materials as 
they have everything at their fingertips in one place.

apidox might provide similar ease .... but then we're back to apidox not 
exactly being high level documentation either.

also, at least in plasma, it's very common for people to mix and match 
frameworks.

oh, one other thing that occured to me today: non-library examples. one 
example that comes to mind would be "how to use Nepomuk to take advantage of 
desktop context awareness"; this is a usage example more than an API example. 
ditto for things like using d-bus to interact with certain applications (e.g. 
krunner, to pick one) or examples showing CMakeLists.txt techniques. where 
would they go? libkdecore? hm..

> In any case, you can't do much development without the API documentation,

yes ... as you note, however, there is the online apidox which many people do 
use (though personally i couldn't live like that ;)

the with-apidox solution doesn't address things like buildbot coverage.

it is compelling in that with the apidox you get examples ... though what i'd 
personally like to see in the future is an offline snapshot of techbase being 
made on a regular basis, aggregated with apidox and examples and provided as a 
single "library" that you can download complete with a simple front end to it.

not unlike, really, what Qt Software has done with Assistant.

that doesn't require everything to live in the same place, however.

> > the links to the source code there are not in a particularly useful state
> > for browsing and using as a template starting point either, they are
> > html'd.
>
> I don't understand why they aren't in a "useful state for browsing" though.

maybe it's just me, but switching between tabs in a browser is less useful/fun 
than either working with the files from konsole or in a text editor / ide.

> > i'd *like* to give people a whole set of examples covering everything
> > possible in KDE that they can compile and play with.
>
> svn external?

ugh...

> Also note my earlier concern that you won't be able to compile and play
> with everything in the examples module without all the sources (or -devel
> packages).

that's normal and to be expected .. and easily worked with in the cmke files, 
so you can just install one set of headers and get just those examples built.

-- 
Aaron J. Seigo
humru othro a kohnu se
GPG Fingerprint: 8B8B 2209 0C6F 7C47 B1EA  EE75 D6B7 2EB1 A7F1 DB43

KDE core developer sponsored by Trolltech

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 197 bytes
Desc: This is a digitally signed message part.
URL: <http://mail.kde.org/pipermail/kde-core-devel/attachments/20081003/b813f4ad/attachment.sig>