Hi folks,
because most of the GIMPers didn't attend the freeform session about
the planed 'unified documentation system', I would inform you what
happend at the session. People came from various projects like
KDE, GNOME as well as translators.
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.
So, we first dicussed an approach on how to lookup documentation from
the help-browsers point of view in the filesystem. 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).
So, most of the results aren't important for the GIMP documentation
system and the help browser. If we can get a bit more precise about the
results of the discussion, the only change to our documentation would be
the desktop files we have to write.
GUADEC was nice, although I haven't had time to attend much of the talks
and sessions. It was a pleasure again to meet all the GIMPers and GNOME
people.
If there are any questions concerning my mail, please let me know :)
[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,
