Hi,
I had some discussions with Daniel Egger on this subject and would
like to tell you what we decided to do and what is still unclear.
Nothing is set in stone yet and comments would be very much
appreciated...
> (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.
We will go for the (b) here. It gives most flexibility since the help
authors can decide whether they want to provide a single "Help is
missing" document or would prefer to provide pages that say "Help for
<topic> has not been written yet."
This makes it necessary to extend the gimp-help.xml format. My
proposal is to add the following line:
<help-missing ref="help-not-found.html" />
If someone can come up with a better name, I'm love to hear about it.
> (2) How do we handle internationalisation?
This isn't completely clear yet. I'll list the open issues:
- The "C" directory should probably be renamed "en". But then, "en_US"
would probably be more correct but it makes things a good deal more
complex.
- Should "en" be used as a fallback when say "fr" doesn't provide help
for a specific topic? Daniel suggested to make this a preference
option. Ideally, there would be a way to specify a prioritized list
of languages but that's clearly something for 2.2. So what can do we
for 2.0? We might want to add a preference toggle "Use english help
as a fallback.".
- I had a look at the way that gimp-help-2 installs the gimp-help.xml
files. We might want to reconsider that. At the moment this is how
it looks like:
${gimpprefix}/help/gimp-help.xml
${gimpprefix}/help/gimp-help.fr.xml
The actual help files are then in directories like this:
${gimpprefix}/help/C/index.html
${gimpprefix}/help/fr/index.html
What I dislike about this is that the base for the references in the
XML files is not the directory the XML file is located in. So
there's some special knowledge needed to interpret the references.
I suggest this structure intead:
${gimpprefix}/help/en/gimp-help.xml
${gimpprefix}/help/en/index.html
${gimpprefix}/help/fr/gimp-help.xml
${gimpprefix}/help/fr/index.html
Of course the gimp-help.xml file could also use absolute URLs so the
help files don't absolutely need to be in the same directory and
might even be online on some web-server.
These are all rather small changes that are easy to implement but we
should better do them now. So if there's consensus on this, I would
like to see this being implemented over the weekend.
Sven
