TODO for the app pages

[Friedrich W. H. Kossebau]

Hi,

this is the maintainer/author of utils.kde.org writing. Which BTW is up-to-
date ;) And easily maintained. Though it shares the bus number with kde-
apps.org, I fear.

Here my 2 cents (and a link to working code, not just words):

<busy contributor summary>
Let's start to use central meta/about data files which feed all places 
describing our software, including the apps pages. Both for consistency and 
low-maintenance.
First build system integration for KAboutData already provided.
</busy contributor summary>

Mercredi, le 3 février 2010, à 12:00, Jos Poortvliet a écrit:
> I don't want to shoot this effort down, but you just can't count on a
> page only accessible by SVN to stay updated. Any page which has to be
> updated more than once a year MUST be a wiki or it won't be updated.

Jos, you being a psychologist (?) I do not wonder you only think of human 
beings. Which I in fact very much appreciate :)

But for some minutes also consider these automates, driven by control code. 
So, what about updating the content with them, i.e. automatically? And, worse, 
not just less than once a year, but every two hours, if needed?

Because the content wanted is (almost) all there, up-to-date and often even 
with multiple translations. In the KAboutData stuffing code (which feeds the 
About dialog) and in the manuals. So what about drawing these data from there, 
without any human interaction?

When developing utils.kde.org I had thought about the problem of maintenance a 
lot. Just consider where for the 4.4 release the new version for a program has 
to be updated:
* About dialog
* manual
* homepage
* software package/stores (e.g. by lsm, spec or similar files)
* bugzilla
* UserBase
* ?
Or consider a new program, how often have all the metadata/aboutdata to be 
transformed/copied to all the different places? And, as especially typically 
with new programs, have changes to be redistributed to all these places?

See, e.g. Okteta:
It isn't listed on kde-apps.org. Because I as Okteta's author have better to 
do then to manually maintain another copy of the About Data. And this fate 
might be the same for many other programs of the KDE SC and KDE ExtraGear. So 
I cannot really consider kde-apps.org _the_ database for software from KDE (as 
in: svn account holders).
On UserBase the version number is wrong. Even with brave Anne and the others 
giving the UserBase pages so much care, which serves so much respect.
Many Okteta packages still point to ww.kde.org as homepage and have an 
outdated description.
You get the fact.

The solution I see is a canonical aboutdata format which is stored at a 
central place and feeds as much other places as possible. Single-source might 
be the buzzword to apply.

The most logical place is again in the svn repository, a file per 
program/plugin, right in the toplevel code dir. This is already the place 
where already the most up-to-date metadata is located, that for the 
KAboutData. And also enables easy access for the buildsystem and translation 
system.

So last weekend I finally sat down and turned a part of this idea into code:
	http://websvn.kde.org/trunk/playground/devtools/aboutdata/

There you can find the program aboutdata_generator for now, which generates 
KAboutData feeding code from an about file.
aboutdata_generator is to be used like Qt's UI compiler:
Add to the CMakeLists.txt
    kde4_add_about_files( YOURPROGRAM_SRCS YOURPROGRAM.about )
and in the source file where the KAboutData instance was previously 
explicitely set, do just a #include <YOURPROGRAM_aboutdata.h> and use the 
class YourprogramAboutData as prefilled KAboutData class.

For Okteta it works already sufficiently :)
The about file used with Okteta as example is this:
http://websvn.kde.org/trunk/playground/devtools/aboutdata/data/okteta.about?view=markup
(data schema is of course not done yet, needs more input from all 
stakeholders, I started only last WE, so this first showing it off to more :) 
)

IMHO UserBase should serve as a collection of usage information, like FAQ, tip 
&tricks, links to related stuff.  It also should be more integrated with the 
(creation of the) manuals we do, because the purposes are quite similar. But 
both should draw all meta/about data from the one single source, for 
consistency and zero-maintenance.

Packagers might also like to be able to script part of their spec file 
creation. The OpenSuse Build system could even fabricate packages without any 
human input besides pressing "Enter". 

KDE-Apps.org (and other software listing places, think freshmeat or zdnet.com) 
could automatically import all the info about our released software, from some 
RSS-feed or another static place with given format.

Back to topic:
So maintenance for these app pages on kde.org should be no argument in the 
future. In fact I think there should be some detailed overviews on kde.org's 
site about the software products we create, to help newcomers get a picture or 
find what they are looking for. Overviews like I did them in utils.kde.org ;)
For the time being entering all the data manually (well, Daniel had done a 
wild extraction script grepping the KAboutData filling code for base data) 
should be acceptable. I think  the system with the about files, 
aboutdata_generator, a commit-hook or better a cron script updating the base 
data of the apps pages should be done in the next two month. Including 
integration with the manual creation.

Oha, long email, but hopefully interesting and motivating. Do you agree, is 
this about file system the way to go?

Cheers
Friedrich
-- 
KDE Okteta - a simple hex editor - http://utils.kde.org/projects/okteta