[Kde-games-devel] How to use KNewStuff3?

[Josef Spillner]

Hello,

my mail intents to shed some light on the issues you raised. Considering my 
current inactive situation, it comes with a disclaimer of probably being 
inaccurate or outdated. Nevertheless, GHNS should support everything an 
application developer wants regarding collaborative data exchange, and if 
something doesn't work right now it needs to be identified and compared 
against the conceptual design of the protocol and the KNS library.
Therefore, I'm glad you point out some under-documented areas of how and where 
to use GHNS.

Am Sonntag, 13. Juni 2010, um 02:03:44 schrieb Ian Wadham:
> What I would like to do is have new-stuff repositories not just for new
> graphics themes but also for:
> 
>   - New sets of levels (currently 1 or 2 sets per year),
>   - Solutions to levels (files of replayable recordings),
>   - Hints on non-Championship levels (English only?) [1],
>   - International high-score bids [2],
>   - Recording of accepted international high-scores [2],
>   - Modifying and deleting new stuff [3],
>   - Restricting access to some new stuff to read-only [3].

The GHNS concept makes it possible to define several categories for one 
application, and actually reuse categories across implementations for all 
"standardised" formats.
So you could have:
- levels and bids just for KGoldRunner
- recordings shared between KGoldRunner and other compatible applications
or something such.

For example, chess recordings use a standardised format (PGN) which therefore 
shouldn't be stored in $KDEHOME but rather be accessible to all chat apps 
somewhere in ~/.chessfiles or ~/.local/chessfiles or whatever the XDG people 
come up with these days as base directory structure.

> The C++ programming of KNS3 looks easy enough, but my
> problems lie in other areas, mainly to do with data definition,
> data storage, user access and user documentation.  For instance:
> 
>   - Where do I actually *store* the new stuff?  On SVN or where?

This depends on the GHNS provider. With the kde-files.org system, the data is 
uploaded and maintained through a web interface. With newstuff.kde.org, the 
data can be maintained in SVN (or maybe Git in the future if there is a 
demand) as well as WebDAV and FTP. A web interface is only available in read-
only mode because so far there doesn't seem to be a demand for full management 
functionality over the web.

>   - What guarantee do I have of continuity of space and URL?

If the data is not too large, you can use the newstuff.kde.org server for 
storage. We set it up so that it doesn't clutter the KDE SVN repositories. It 
has some 4 GB free space and I'm sure we'll get more if needed. There is 
versioning support available to guarantee stable URLs for access by parallel 
KDE application releases, but this feature is admittedly not really used much 
yet.

>   - How do the users know where to find it?

The users shouldn't know where the data comes from (downloads) or goes to 
(uploads). Advanced users should be able to find it out for reasons of desktop 
control and transparency, but most users don't care. They should simple use 
the provided KNS classes and standard action to fetch or transmit the data.

>   - How do the users go about preparing and uploading stuff?

In KNS2, there was a generic upload wizard to specify the file, preview, 
licence and other metadata. The file and preview generation was application-
specific logic.
There have been some changes in KNS3 regarding upload, and I haven't seen 
upload in action yet. Perhaps your game is a good prototype to test it :-)

>   - Where do you store the doco on formatting data, how to upload
>     stuff and how to use stuff of various kinds?
>   - How do the users know where to find the doco?

Partially in the manual (for end users) and partially on techbase, I'd say.

>   - What is the translation policy for text in new stuff?

There used to exist some scripts in Hotstuff SVN to convert between the GHNS 
XML format and the desktop format understood by KDE's translation system. If 
they're used somewhere is beyond my knowledge, but from an academic point of 
view it's a solved problem ;)

>   - Last but not least, how do you program multiple sources of
>     different kinds of stuff?

This should work out of the box. KNS supports multiple GHNS providers on the 
conceptual level. One example would be to combine a stable KDE repository with 
a special repository at events/lectures where users can generate application 
extension items such as levels, test them and throw them away afterwards to 
complete the exercise.

> I saw a thread on the last question and have made a note of it
> for future reference.  It seemed to involve having a separate
> new-stuff instance for each type of data and was not, IIRC,
> considered to be very elegant.

The only major problem on it, to my knowledge, was to ensure that if "stuff" 
is uploaded to two providers it can be identified as identical.

Josef