GUADEC 2005 - unified documentation system

[Roman Joost]

Hi folks,

still after the GUADEC and our freeform session, I want to summarize our
results by this mail. Please verify, if I understood everthin correctly.
If everthing is fine, I want to write our results in full on the wiki
page[2] so everyone can join the discussion.

First, we discussed the pros and cons of the current help browser
situation. There is the KDE help browser which provides not only KDE
documentation, as well as the GNOME documentatation with some trickery.
Most agreed, that scrollkeeper isn't the best approach for finding
documentation and has some drawbacks (eg. a generated ID), which I don't
want to elaborate more here.

KDE uses an extended key set for looking up documentation in '.desktop'
files[1]. Every agreed, that using these keys for all help browsers
would solve a lot of problems scrollkeeper had.

To summarize up:

    - a desktop file installed in the #XDG_DATA_DIRS/help or a hidden
      $XDG_DATA_DIR in the home directory of the user will point to the
      documentation in the filesystem (we also discussed a naming schema
      which is available at the wiki[2]). The possibility to install
      documentation in the users home directories provides the
      opportunity, that users can independendly install additional
      documentation. The $XDG_DATA_DIR in the users home directory
      should be indexed by the help browser first, though.

    - localized versions of the documentation are seperated by folders.
      The language is determined by the foldername, which should be an
      ISO code. Each subdirectory should contain an additional desktop
      file to provide additional information for the help browser. This
      is currently a bit vague what the desktop files in these subdirs
      should provide (could be fallbacks urls to other ids or documents)

    - if no localized version can be found in the subdirectories, a
      fallback to the 'default' language is considered or at least the
      default documentation (in whatever language it is written).

Thanks for the great session and all involved persons. Comments are very
welcome :)

[1] - http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-0.9.4.html#recognized-keys
[2] - http://www.freedesktop.org/wiki/Standards_2fhelp_2dsystem

Greetings,
-- 
Roman Joost
www: http://www.romanofski.de
email: romanofski at gimp.org
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/xdg/attachments/20050607/e45cda11/attachment.pgp