examples

[Aaron J. Seigo]

On Monday, December 5, 2011 09:24:07 Oswald Buddenhagen wrote:
> On Mon, Dec 05, 2011 at 12:05:13AM +0100, Aaron J. Seigo wrote:
> > source code examples are to live in an examples/ directory within the
> > given
> > framework git module. to put it simple: i object :)
> 
> and i deflect. :P
> this topic was discussed ad nauseam in qtdf.
> 
> examples have to live in their parent module so they can be linked from
> the docs.

that's a very interesting point. however, in kde's apidox we don't currently 
tend to refer to examples, so unless we change that behaviour we can ship a 
qch file with kdeexamples and have the same (or rather: better) result as we do 
now. for Qt, where docs sometimes refer to examples, this is indeed more 
difficult.

> bigger examples with multiple dependencies (aka, demos) can be
> aggregated in a separate module (qtdoc in qt, due to the surrounding
> documentation).

i agree, that makes sense ..

> > kdeexamples exists as a way to bring together
> 
> that should make you think already, given the objective of frameworks.
> ;)

the reason frameworks (and Qt) are modularizing are for technical reasons, 
with some lesser social / human ones mixed in.

the reason for keeping examples together is that people then don't have to 
search for examples on how to use phonon, then sonnet, then QML in plasma, 
then solid, then .. they grab one repository that is a full library (refering 
to a library of books, not a .so ;).

examples are educational, and that's why i favour a "full library" approach. 
in this case i think it is more important to think about / listen to our 
audience than to make a technically convenient solution.

> > prevents developers, who usually work with pre-packaged binaries and
> > not the upstream sources, from having to fetch each and every
> > framework tarball just to see examples for it.
> 
> i call that a distribution problem. examples should be distributed as
> source code in noarch "binary" packages (either as separate -examples,
> or part of -doc).

which doesn't happen. we could perhaps encourage packagers to do this, which 
means asking them about the feasibility of this. doesn't do much to help 
people on windows, though.

-- 
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 Qt Development Frameworks
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part.
URL: <http://mail.kde.org/pipermail/kde-frameworks-devel/attachments/20111205/7b1f5bfe/attachment.sig>