Hi,
I mentioned i18n and the help system in an earlier mail today but it
probably makes sense to go into some detail. I've added the help
authors to the Cc: because of course this affects their work and their
advice would be very helpful here...
First, a short summary of how things work at the moment:
In GIMP we added help IDs to all dialogs, all menu entries and some
more GUI elements. They are all defined in app/widgets/gimphelp-ids.h,
so here we have a complete list of all IDs. Now, if the user presses
F1 in a dialog or with the mouse hovering over a menu entry, or she
uses Shift-F1 to examine user interface elements like for example a
button in the toolbox, the following happens:
GIMP looks at the gimprc value "use-help". In case it is set to "no",
things stop right here. If help is enabled, the help extension (a
plug-in) is started. It is passed a list of all help domains that
plug-ins might have registered on startup. This only happens on the
first help request, the extension will keep running from now on. Now
that the extension is running, a request for the selected help ID is
sent to it, together with an identifier for the help domain and a
language identifier. At the moment the language identifier is always
'C'.
The help extension now parses the XML file for the requested help
domain. This file maps help IDs to URLs. The file is parsed on the
first help request for a particular help domain. Since the help
extension keeps running, it will know the mapping table the next time
help is needed from the given help domain. If the given help ID can be
mapped to an URL, the help extension calls either the helpbrowser or
the webbrowser plug-in with that URL. Which plug-in is called depends
on the gimprc setting for "help-browser".
The helpbrowser plug-in is basically just a simple HTML browser and
offers the same API as the webbrowser plug-in. It takes an URL and
displays it.
OK, so far so good...
Now here are the open points:
(1) What should happen when an ID cannot be mapped to an URL? At the
moment we open a dialog to inform the user that the help-id is
unknown. That's pretty confusing for the casual user and I think
we can agree that this should not happen.
I can think of two solutions for this problem:
(a) Make sure that gimp-help-2 provides URLs for all IDs. Not
necessarily unique URLs. All IDs for that no help exists could
point to the same URL.
(b) Extend the gimp-help.xml format to allow to specify a fallback
URL that should be used when no other mapping is given.
The second solution seems to make more sense since it's easy to
miss an ID and we might want to add more IDs at any time.
(2) How do we handle internationalisation? Since there are help
translations already, we should think about how we want to use
them. At the moment, for each language, a gimp-help.xml mapping
file is installed. I think this is good and doesn't need to be
changed. But there are some implementation details that are not
clear to me yet.
Let's use an example. Please note that everything below is
hypothetic since there is no code in the help system for handling
languages yet (the help content on the other hand does exist):
Our GIMP user is french and runs gimp with LANG=fr_FR. So "fr_FR"
is what gets passed to the help extension. It will check if help
exists for "fr_FR" and will detect that this is not the case. It
should then strip "_FR" from the language identifier and will find
that there's help for "fr". It parses the mapping table and
attempts to map the requested help ID to an URL. If it finds one,
good, call the browser to display it and the job is done. Now what
is supposed to happen if there's no french help written for this
ID? Again I can imagine two possible solutions. Both are however
based on the assumption that we decide for (1b).
(a) Use the fallback URL from the mapping file. This would
probably point to a french page that explains that no help
exists for this topic yet and that invites the user to join
the gimp-help team and write it.
(b) Try to get help from the 'C' branch of gimp-help-2. There
might exist english help for this topic and we could show the
user the english help page. In case there's also no english
help, it would probably be best to do what I suggested in (a)
and in case there's no fallback URL for the french version, as
a last resort use the fallback URL for C.
I am undecided here. Since I speak english quite well, I would of
course prefer to get english help if no german help is
available. But what about the casual user? Should we present
english help to her or would it be better to say, sorry, there's
no help written in your language?
If we decide for (a) here, we would have to add some simple rules
that assure that users running gimp with LANG set to "en_US",
"en_CA" and similar are thrown to the C language. Or we should do
it the other way around, rename C to en and make sure that LANG=C
is mapped to en. I sortof favor the latter because I never liked
the fact that the english help lives in a directory called "C".
Comments, anyone?
Sven
