GUADEC 2005 - unified documentation system
romanofski at gimp.org
Tue Jun 7 17:24:02 EEST 2005
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 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. 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). 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
 - http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-0.9.4.html#recognized-keys
 - http://www.freedesktop.org/wiki/Standards_2fhelp_2dsystem
email: romanofski at gimp.org
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Size: 189 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/xdg/attachments/20050607/e45cda11/attachment.pgp
More information about the xdg