KNewStuff2 Feature Guide
========================

This document describes the options an application author
gets when implementing support for KNewStuff under KDE 4,
better known as KNewStuff2.
The style of writing is however not very developer-centric
at times, so anyone who wishes to find a feature reference
can consult this guide.

Key features
------------

* KNewStuff2 implements the GHNS specification!
  The standard is maintained at http://ghns.freedesktop.org/
  and ensures a consistent and well-defined behaviour.

* KNewStuff2 supports the Desktop eXchange Service protocol!
  DXS is a web services based implementation of the GHNS protocol
  with some extensions, mostly resulting in more direct user
  interaction.

* KNewStuff2 helps making KDE the Kollaborative Desktop Environment!
  Along with other internet-integrated aspects of the desktop,
  the library helps users working with each other from remote places.

Complete feature list
---------------------

The features have been designed to blur the line between data producers
(the creators) and data consumers (the users), to arrive at a more
flexible notion of data contributors.
Still security and privilege handling does play an important role.

* Data creation
  An application which allows the creation of data files integrates
  the KNewStuff upload dialog. To upload a file, a preview image should
  be given (may be autogenerated if the KFile plugin exists),
  and the important descriptive fields such as name, author and
  licence must be filled in by the uploader. These can however be
  re-used from previous sessions, so that the process of uploading
  is as easy as possible.

* Data improvement
  To update an existing piece of data, instead of filling out the
  descriptive fields again, a simple re-upload using an incremented
  version number can take place.
  For the users downloading the data, versioning control might then
  allow to retrieve the data from previous versions.

* Browsing
  Each provider can offer different "views" or feeds based on
  criteria such as "latest items", "most popular items" or
  even custom ones such as "contest xyz winners".
  With DXS, support for find-as-you-type search and entry caching
  should be possible.

* Installation
  The installation process can involve integrity checking of the
  downloaded data (using a hash sum), authenticity checking (using
  an OpenPGP signature), extraction of the data file to a set
  of files or a whole directory, and invoking a post-installation
  handler to notify the application or run an external script.

* Uninstallation
  Installed items can be uninstalled at any time. For this reason,
  the metadata is kept for each installed entry in an entry registry.

* Translation
  Each user can add summary and title translations at any time.
  However depending on the site policy, these might only take
  effect after an admin review phase.

* Subscriptions
  A user can subscribe to an entry, and be informed when an
  update is available. With DXS, the list of subscriptions can
  be queried as a virtual feed.

* Versioning
  Subscription and (un)installation automatically lead to a simple
  versioning schema. This option is not shown by default unless a
  particular application wants to make use of it.

* Site maintenance
  Users can request removals of entries which are bogus or might
  require other administrator attention.

* Provider support: Hotstuff
  The Hotstuff server-side GHNS framework is designed to be fully
  compatible with KNewStuff2. In particular, it supports authenticated
  user operations and old KNewStuff compatibility file formats.

* Cached data
  Downloaded data can be kept in a cache to speed up looking for entries and
  for instantaneous display of the download dialog.

