Hi,

here's a short list of things that need to be looked at before 2.0. Perhaps we should have bug-reports for these...

- gimp.spec should not be in the tarball

That's what Ville, Yosh and me think would be best. Need to remove gimp.spec from configure.in and somehow substitute things by other means. Ville promised to look at this in time.

- need a final splash image

I am counting on Jimmac to drop a final version into CVS.

- review debug output

I think we removed most of it or put it into GIMP_UNSTABLE #ifdef's. But it would be a good idea to check if there's anything left. Not that it would really hurt but it just doesn't look professional.

- test help and if it works, remove or #ifdef debug output

The new help plug-in has code that used to live in the helpbrowser plug-in. Brix moved it into a plug-in of its own so that the webbrowser can be used to access the help pages. This has been done after pre4. Seems to work fine, but should see some more testing especially on windows. There's massive debug output in there that shouldn't end up in the final version.

- consider to add localization support to the help system

The API is in-place, so we can easily do this for 2.0.1 but it would of course be nice to get this into 2.0. Simply because there is translated help available already but at the moment it cannot be used from The GIMP. Mitch wanted to look at this.

Did I miss anything? I certainly did...

Sven

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

Hi,

Andreas Røsdal writes:

I've made a suggestion splash image for Gimp, which uses some elements from previous splash images in development releases. Please consider it.

That would be basically going back to the 1.0 splash screen and I don't think that's a good idea. But thanks for your efforts.

Sven

Hi,

raymond ostertag writes:

The third and good solution for me is to redefine the ID's in gimphelp-ids.h with the gimp-help team and avoid to do this like a mechanical stuff.

Sorry, but this is not an option. The help IDs are defined by the application, not by the help authors. The help authors are free to map several help IDs to the same page. Actually I don't see your problem with the help IDs. To me they seem well choosen. They allow to provide very fine-grained help but thanks to the mapping file (gimp-help.xml), the help authors are not forced to provide help for each and every help ID.

I did'nt test anything until now but because some ID's are going very deap in our help files and I don't think that we can define the same ID in different place

Of course you can do that. What makes you think you couldn't?

Sven

Hi,

Tim Mooney writes:

- gimp.spec should not be in the tarball

Why not?

Because our experience in the pre-releases has shown that it is extremely difficult to provide a working spec file. And even if we managed to provide on, it would be specific for a particular distribution. So we should either provide spec files for all major distributions as well as portsfiles for the various BSD flavours and rules to build Debian packages and a configuration file for a Win32 installer or no such file at all. We decided for the second option.

Sven

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 has not been written yet."

This makes it necessary to extend the gimp-help.xml format. My proposal is to add the following line:

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

Hi,

I'd like to give an update on the list of open issues that I posted two days ago...

- gimp.spec should not be in the tarball

Done.

- need a final splash image

I've opened a bug report for this (http://bugzilla.gnome.org/show_bug.cgi?id=136993). Got no feedback yet but I am not (yet) worried...

- review debug output

Has been addressed and seems completed.

- test help and if it works, remove or #ifdef debug output

The new help plug-in has code that used to live in the helpbrowser plug-in. Brix moved it into a plug-in of its own so that the webbrowser can be used to access the help pages. This has been done after pre4. Seems to work fine, but should see some more testing especially on windows. There's massive debug output in there that shouldn't end up in the final version.

I haven't received any feedback yet, so I assume that it is working for everyone? The debug output should probably stay for now. It might be useful in case that we address the i18n issues with the help system.

- consider to add localization support to the help system

The API is in-place, so we can easily do this for 2.0.1 but it would of course be nice to get this into 2.0. Simply because there is translated help available already but at the moment it cannot be used from The GIMP. Mitch wanted to look at this.

I've explained this in more detail in other mails and it seems that we probably want to change the install location of the gimp-help.xml files. This should happen before 2.0 gets out. So I'd like to treat this a bug that should be fixed before 2.0 but it should not be considered a blocker. If we don't get around to it, we will have to live with the way it's done right now.

This is being tracked in http://bugzilla.gnome.org/show_bug.cgi?id=136996

Sven

Hi,

I've now checked in my changes to the GIMP help system that make it possible to use help written in the user's language. This closes bug #136996. Here's a short explanation of the implementation:

I've added a gimprc token called "help-locales". This isn't exposed anywhere in the GUI yet and it defaults to NULL. But it should allow us to configure things in a more flexible way later. If you want to play with this, you can for example request help in french, swedish, german, english with descending priority by adding the following line to your gimprc:

(help-locales "fr:sv:de:en")

In case this new option is not set, the locale is taken from the user's environment.

When a help page is requested, the help is searched in the list of locales. In case no matching reference was found, a fallback reference is searched in a second walk over the locales. If there's still no help, the help plug-in checks if the default help domain (en) is available at all and will try to give a helpful error message.

It would be nice if the gimp-help-2 team could add pages for missing help content and add or
similar to the gimp-help.xml files for the different languages. As soon as these fallback pages are available, it would be nice to have a new help snapshot that people can install with 2.0rc1 to give this stuff some testing.

I already changed the Makefile in the gimp-help-2 module to install the help files according to the new scheme that we discussed here earlier.

Sven