On Mon, Aug 18, 2003 at 06:38:06PM +0200, Sven Neumann wrote:

Translation of the help pages is another subject that should be discussed beforehand. I don't think the current approach of translating the XML source in place will scale well when the number of translations increases. There are some tools available that automate the process of extracting translatable strings from XML sources and merging the translations back. We should consider to use them.

Maybe you mean, writing the translation to *.po files? I saw this, during the work on a new setup of a zope server. We used "Plone" and they translated all these english stuff into other languages using *.po files. I don't know which will be best technical way for write a translation. Daniel said, that this way isn't bad as it seems, because you can controll the granularity of the generated files or split up the xml docs.

Perhaps this mail can get a discussion started. We should also try to involve more people early.
I suggest we ask for volunteers on the gimp-user list and other user forums.

Yes - i agree. We need many contributors to get a good manual done. I think, the best way is to get a section on the gimp page (i asked Daniel earlier). There we can show the current status of the manual, and ask for help. Additionally we can setup some help pages, to get involved. I think, we need some writers, who are responsible for a language file (the translation file).

So, to summarize my opinion. I think we need:
- a webpage where we can upload the current cvs for the online user

- a status page

- a contributing page, where everyone can get involved

Greetings,

On Mon, Aug 18, 2003 at 07:40:14PM +0200, Sven Neumann wrote:

I don't really care. I just wanted to be sure that you considered using these tools. If you dislike them and decided to go for a different solution, I'm fine with that.

I think, that Daniel Egger and Mel Boyce setup the newer gimp-help-2 module. For this reason, i think that Daniel know exactly what he is doing, to get a good documentation done. I can currently agree with him. If i understand you right, you just wanted to take care, that no one invest time to get a new documentation done which is completly useless. So, we're on a good way to get a "basic" documentation done, which is useable for the Prerelease of the GIMP 2.0. Iam looking forward to get this done and hope, that more contributors join us, when a site is up ...

- a webpage where we can upload the current cvs for the online user

- a status page

- a contributing page, where everyone can get involved

That's exactly what I was trying to say. I was asked today on #gimp how to contribute to gimp-help and I wasn't sure what to respond. A web-page to refer people to would certainly help a lot.

I'll setup up some pages for the module, but where can i upload these pages? A good way to update the status of the docs is an account, where i can sync my help and the help docs on the server. If it isn't possible to upload these pages to the current website yet, i'll create a "temporary" location for the these docs. This isn't the best way, because "temporary" means difficult for the users and upcoming contributors. I uploaded docs of the gimp-help-2 module on a university server, since we might get a section on the gimp page.

http://www.kuhcampus.de/~roman/gimp-help-2/

Maybe one of the GIMP Website Team can help me?

Greetings,

On Mon, 18 Aug 2003 20:12:06 +0200, Roman Joost wrote:

I'll setup up some pages for the module, but where can i upload these pages? A good way to update the status of the docs is an account, where i can sync my help and the help docs on the server. If it isn't possible to upload these pages to the current website yet, i'll create a "temporary" location for the these docs. This isn't the best way, because "temporary" means difficult for the users and upcoming contributors. I uploaded docs of the gimp-help-2 module on a university server, since we might get a section on the gimp page.

http://www.kuhcampus.de/~roman/gimp-help-2/

Maybe one of the GIMP Website Team can help me?

I suggest that you keep this temporary URL for the next two or three weeks. The new web site (currently mmmaybe.gimp.org) should replace the old one soon and it will be easier to set up the correct URL after all parts of the new site are in place.

Regarding the "final" location, I would suggest something like: http://www.gimp.org/docs/help/
The web site is under CVS control (module "gimp-web"), so there should be no problem for synchronizing the contents if you have write access to CVS.

-Raphaël

On 18 Aug 2003, at 20:25, Raphaël Quinet wrote:

On Mon, 18 Aug 2003 20:12:06 +0200, Roman Joost wrote:

I'll setup up some pages for the module, but where can i upload these pages? A good way to update the status of the docs is an account, where i can sync my help and the help docs on the server. If it isn't possible to upload these pages to the current website yet, i'll create a "temporary" location for the these docs. This isn't the best way, because "temporary" means difficult for the users and upcoming contributors. I uploaded docs of the gimp-help-2 module on a university server, since we might get a section on the gimp page.

http://www.kuhcampus.de/~roman/gimp-help-2/

Maybe one of the GIMP Website Team can help me?

I suggest that you keep this temporary URL for the next two or three weeks. The new web site (currently mmmaybe.gimp.org) should replace the old one soon and it will be easier to set up the correct URL after all parts of the new site are in place.

Regarding the "final" location, I would suggest something like: http://www.gimp.org/docs/help/
The web site is under CVS control (module "gimp-web"), so there should be no problem for synchronizing the contents if you have write access to CVS.

Shouldn't support for documentation writing take place on http://developer.gimp.org, rather than http://www.gimp.org?

Am Mon, 2003-08-18 um 18.38 schrieb Sven Neumann:

I think we should discuss how to proceed with the help system for gimp2.

At the moment we're at full speed towards some usable content both in English and German. Roman is doing a fantastic job in translating and filling the gaps and Dave greatly helped drawing some attention.

I don't think there's much to say or discuss which hasn't been said or discussed a few weeks ago. Please refer back to that thread before reiterating everything again.

Areas which need acting is the connection between the docs and the GIMP itself. Though since the consensus seemed to be that it's somehow possible to interconnect between XML id's and filenames I'm happily waiting for someone to program the bridge so we can get the help rocking.
Rest assured we're ready to match up with any code that appears on the horizont from the document point of view in no time.

Since the question popped up again, the primary contact person would be me (Daniel Egger ) for all concerns or Roman (Roman Joost ) especially for documentation concern and the German translation.

I hope we'll get a website in place rather soon for those not being able to read mail or cope with CVS.

Thanks for listening.

Am Mon, 2003-08-18 um 23.54 schrieb Sven Neumann:

The discussion about the new help system stopped at some point and we haven't outlined a detailed plan yet.

I though you had a plan? Since I couldn't convince you to render DocBook directly as yelp does it sounded pretty much like you would know how to realise your mapping idea. I'd be more than happy to discuss any additional infrastructure you need from us to set it up.

We also haven't discussed how localization of the help pages should be handled.

There's one officially supported way in DocBook which is called profiling*1 and which is what we doing. Since you only care about the generated HTML, I cannot see why you want to care about the source also.

It's hard to see the benefits other ways provide especially since the methods are already in place and fully working, yet there's not a simple limit in sight.

I'd be glad to explain how it works and why it's a great idea if it helps; however so far your complaint sounded unfounded and bogus to me.

This hasn't been much of an issue so far but as I noticed that you started to work on a translation, I thought we should bring this up. There seemed to be much consensus on the help system lately but the lack of a write-up makes it hard to do the changes to the helpbrowser that will be needed to use the new help pages.

You said HTML and we're working to provide you exactly that; if you change your mind we'll adapt. If there needs to be anything documented about the whole setup I'd be happy to do it right away.

*1: Profiling in DocBook means transformation of input into output based on attributes placed on arbitrary tags. Obviously for this purpose we're the language (=lang) attribute.

Am Die, 2003-08-19 um 00.44 schrieb Sven Neumann:

From looking at the CVS module I didn't have the impression that the file structure is prepared for i18n. If you decided to keep all translations of a topic together in the same file that's fine, but shouldn't the C directory be completely dropped then?

Though about it but that would need someone with access to the CVS server and since we're not in a hurry....

Back when syngin and I started profiling was simply unusable so we started like we stopped with the old system to have a somewhat familiar environment.

What really concerns me is how the generated HTML pages in different languages will be organized.

Every one in it's own distinct tree. The transformation has to be started once for each language and will spit out the document or a directory for it.

The helpbrowser will have to know about this

I can't see a reason why, unless you want to mix languages, but even then one can point to a different directory, so...

We cannot start to work on this unless there is at least a sample XML mapping file and perhaps one or two sample help pages.

You'll get it. I still have no idea how the mapping is supposed to work and thus look. Once we defined a format and a meaning I'll set up a stylesheet to produce it. The sample pages we already have, we just take it from the documentation. :)

I have been waiting for these files and perhaps a short writeup explaining the concept for a few weeks now and thus decided to bring the topic up again. Rest assured that I remember what has been discussed a few weeks ago but the dicsussion ended at a point where there wasn't anything but vague ideas. It's impossible to start an implementation based on this.

I'm terribly sorry, but it was your idea so you are the one who needs to explain how it's supposed to work. I disliked it from the beginning because I've experienced a lot of friction with mapping to automatically generated HTML files in the past but since I'm not the one having the time to implement it, I certainly have no voice in here....

Am Die, 2003-08-19 um 01.35 schrieb Sven Neumann:

I have a plan but I felt it's up to you to provide a sample XML mapping file and some sample help pages for us to play with.

Let's discuss this XML mapping, I'm still clueless...

What I care about is how the generated HTML files in different languages will be structured since the helpbrowser will have to choose the appropriate files based on the users locale and it will probably have to know how to fallback to the english version.

I hope it's convenient for you to have different directory trees per language, how they are christened is your call. :)

I'm not saying that this approach is suitable for larger documents but I know that there are tools available that claim to be.

The problem here is that documentation is 1:1 translateable in contrast to messages which are quite. The catalog system requires to have one master language and several slaves; I have a strong dislike for this because every language should have a right to evolve on its own. No English master and also no fallback to English. If the content between the different languages diverges -- hey' so be it. It may as well happen that there will be a German subsection with some special information just suitable for Germans. Or that the German version will grow faster than English; that solely depends on the writers.

If you look at the generated tips file you will notice that it becomes rather hard to handle with the amount of translations in there. That's why I said that your current approach doesn't scale well.

Since there is no measure it doesn't make sense to talk about scaling in this sense. Nothing prevents me to say:

Bar Baar
Bar I said
&foo-bar-de;
&foo-bar-no;
&foo-bar-en;

And then have three files all just containing the content for this section in the language.

There simply is no limit, if a file grows too large to handle sensible we'll split it into several. Heck, I could even use a XSLT to do it automatically.

Am Die, 2003-08-19 um 02.31 schrieb Sven Neumann:

I think I explained the reasoning in my last mail. Oh well, let me do it again then...

This does *not* make sense.

The helpbrowser will have to choose the language based on the users locale, it thus needs to know how the files are organized language-wise. I can imagine at least two possible solutions to this problem. Either the mapping table knows about the available languages or we encode the language into the directory structure as we did for 1.2.

And where's the problem? Why are we talking about 15 seconds worth of work in lengths? You'll get exactly that, right away. Check out CVS, run autogen.sh, configure and make; it will create one directory structure for German and one for English.

Huh? I thought we were past this point about a month ago. What exactly didn't you understand about it?

What the mapping looks like! You keep insisting that it's deadly trivial though you simply cannot come up with something like an example and even ask *me* to provide one. Sorry Sven, this is really insane!

Actually it was Mitch's idea. Perhaps he should continue to explain it then.

Exactly, why are you bothering me with an example?

I've explained it several times and you keep saying that you dislike it although you didn't understand it.

For you (again) in plain English: I dislike the idea of using HTML accessed from some helpbrowser using a mapping.

And here's why: I don't know how you want to control the granularity of the generated HTML files; you'll get lengthy and supershort files which will make browsing the help real fun.

It will probably be best if I keep myself out of this then and stop to try to work with you.

Great, sounds like plan that finally might work.

On Mon, 18 Aug 2003 22:08:14 +0200, "Branko Collin" wrote:

On 18 Aug 2003, at 20:25, Raphaël Quinet wrote:

On Mon, 18 Aug 2003 20:12:06 +0200, Roman Joost wrote:

I'll setup up some pages for the module, but where can i upload these pages? [...]

I suggest that you keep this temporary URL for the next two or three weeks. The new web site (currently mmmaybe.gimp.org) should replace the old one soon and it will be easier to set up the correct URL after all parts of the new site are in place.

Regarding the "final" location, I would suggest something like: http://www.gimp.org/docs/help/
The web site is under CVS control (module "gimp-web"), so there should be no problem for synchronizing the contents if you have write access to CVS.

Shouldn't support for documentation writing take place on http://developer.gimp.org, rather than http://www.gimp.org?

Sorry, I should have mentioned that the above URL was refering to the "stable" help pages. The URL for the development of the help pages could of course be different, and it could be hosted on the developers' site.

As we have discussed during GIMPcon, the next release of the GIMP will not contain the help system in the default package. The help system will be shipped as a separate package (with its own release schedule) and it will be up to those who build and distribute binaries to decide if they ship them together or not. If a user tries to access the help system while it is not installed, the GIMP should display a message saying that the corresponding help page is not installed and suggest to install the missing package. But it should also provide a link to a copy of the help pages available from www.gimp.org. This is what I was refering to in my previous message: http://www.gimp.org/docs/help/ This URL would always contain the latest stable version of the help pages.

This URL (a prefix, actually) would be known by the GIMP so that those who do not have the gimp-help(-2) package can access the online help.

-Raphaël

On Tue, 19 Aug 2003 01:35:33 +0200, Sven Neumann wrote:

What I care about is how the generated HTML files in different languages will be structured since the helpbrowser will have to choose the appropriate files based on the users locale and it will probably have to know how to fallback to the english version.

I was wondering... Is it really necessary for the help browser to know how to fallback to the English version? This could also be done by the build system for the help pages, and it would even be better for encouraging the users to translate the pages. Let me explain...

Let's assume that we have one tree per language (similar to gimp-1-2). Instead of shipping a set of help pages that could have missing pages for some languages, we set up a build system for the help pages in such a way that it ensures that all help pages from the "C" directory are automatically added to all other languages. The top-level directory for each language would contain a template file with the following message in the corresponding language: "This page has not been translated yet to . The English version is included below. If you want to help other GIMP users, please consider submitting a translated version of this page to the translators at ."

So when a page is missing in some language, the corresponding page from the "C" directory would be copied by the build system (not by the GIMP itself) and would include the text mentioned above in order to encourage users to contribute their own translations. The message could also include a link to the online version of the help system (hosted at www.gimp.org or developer.gimp.org) so that the users can check if the latest version of this help page is already translated or not.

-Raphaël

Am Die, 2003-08-19 um 11.52 schrieb Sven Neumann:

The current helpbrowser does it that way. But, no, it isn't necessary and that's why I wanted to see it discussed. Since Daniel obviously refuses to do that,

Do not lay words in my mouth!

I won't be able to do work on the implementation.

This is a poor mans' excuse.

I also don't want to work on it any longer unless Daniel changes his

^^^^^^^^^^^^^^^^^^^^^^^^^

This is what you wanted to say, nothing else. Really sad...

Am Die, 2003-08-19 um 09.48 schrieb Raphaël Quinet:

following message in the corresponding language: "This page has not been translated yet to . The English version is included below. If you want to help other GIMP users, please consider submitting a translated version of this page to the translators at ."

I'm not sure I exactly like this idea completely (ie. the implied automatism) since I don't want to enforce 1:1 translations, however it seems like a bright idea to set it up for completely uncovered topics.

Not that we have any translations at the moment which are incomplete enough so this would matter, but if people like it, I'll certainly put it on the list.

Daniel Egger (degger@fhm.edu) wrote:

Am Die, 2003-08-19 um 11.52 schrieb Sven Neumann:

The current helpbrowser does it that way. But, no, it isn't necessary and that's why I wanted to see it discussed. Since Daniel obviously refuses to do that,

Do not lay words in my mouth!

I won't be able to do work on the implementation.

This is a poor mans' excuse.

I also don't want to work on it any longer unless Daniel changes his

^^^^^^^^^^^^^^^^^^^^^^^^^

This is what you wanted to say, nothing else. Really sad...

Hi Daniel, Sven.

Would you please *both* step back a bit and look at the mails you just wrote? They make you both look very silly.

Apparently there are some gripes between you both and you probably should talk in private mail about that. But I really do not understand why you seem impossible to discuss this in a reasonable manner. Threatening to stop development on gimp-help and - vice versa - to impute that that was the whole point is not helpful at all.

I'd like to ask you to stop discussion for today and tell each other in a non-pissed off way tomorrow on this list, what you need from each other.

From my point of view neither the gimp-help team nor the

gimp-developers-team have proposed a way to do the linking between gimp and gimp-help and this obviously is necessary to integrate the help with the Gimp.

Sheesh!
Simon

On Tue, Aug 19, 2003 at 02:39:23PM +0200, Simon.Budig@unix-ag.org wrote:

Would you please *both* step back a bit and look at the mails you just wrote? They make you both look very silly.

I can fully agree with Simon. Since i was starting to work on the documentation, i can't image, why so many people left the project. In my point of view, it seems, that the problem for the gimp project is the discussion among each other.

I'm a newbie here, but if everyone discusses the terms in that way, no one want to contribute. I mean - is it really necessary, that everyone fights against the others?
I think, there is lots of work to do and no fights. I think everyone is an adult person and not a child - so we can discuss this in a better way.

Thank you

-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1

Has anyone else noticed how the bugs@gimp.org spam is getting a little out of hand? perhaps now would be a good time to change that address.

- -- Dan
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.2 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQE/Qjunad4P1+ZAZk0RAgdFAJ0a9mlxy/947bJOSayuAoj1WwrxcQCglaSS SBUYodfIqr6pPFACax1mQd4=
=zbTP
-----END PGP SIGNATURE-----

On Tue, 19 Aug 2003 08:00:55 -0700, Daniel Rogers wrote:

Has anyone else noticed how the bugs@gimp.org spam is getting a little out of hand? perhaps now would be a good time to change that address.

Well, this looks like another Microsoft worm spreading like wildfire. This is yet another variant of the Sobig worm: http://securityresponse.symantec.com/avcenter/venc/data/w32.sobig.f@mm.html I got several hundred copies of it in the last 6 hours. Most of them came from bugs@gimp.org. Sigh!

We cannot easily change that address because that would require changing all gimp bugs, which are using this as the contact address. But as I suggested during GIMPcon, we could configure this address so that it accepts mails from Bugzilla only. Anything that is not coming from Bugzilla would be bounced back to the sender.

-Raphaël

On Tue, 19 Aug 2003, Daniel Rogers wrote:

Date: Tue, 19 Aug 2003 08:00:55 -0700 From: Daniel Rogers
To: gimp-developer@lists.xcf.berkeley.edu Subject: [Gimp-developer] bugs@gimp.org spam getting a little out of hand

-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1

Has anyone else noticed how the bugs@gimp.org spam is getting a little out of hand? perhaps now would be a good time to change that address.

Banning attachments and HTML email might be a tolerable compromise.

At worst any real people sending to bugs will know to resend or use http://bugzilla.gnome.org instead if they are unwilling or unable to not send as HTML.

Just a suggestion to consider, feel free to kill the address if you prefer.

- Alan

On Tue, Aug 19, 2003 at 08:58:25PM +0100, Alan Horkan wrote:

Banning attachments and HTML email might be a tolerable compromise.

A compromise that wouldn't even catch 1% of the mail isn't torable in my opinion (especially as it's not possible to filter for this).

How can one unsubscribe from bugs@gimp.org, by mailing yosh?

Just a suggestion to consider, feel free to kill the address if you prefer.

The problem mail does not come from bugs@gimp.org, but through bugs@gimp.org. Filtering for it is close to impossible, as the problem is not spam, but replies to spams send by others.

On Tue, Aug 19, 2003 at 06:20:43PM +0200, Sven Neumann wrote:

Hi,

On Tue, 2003-08-19 at 18:04, Rapha??l Quinet wrote:

We cannot easily change that address because that would require changing all gimp bugs, which are using this as the contact address. But as I suggested during GIMPcon, we could configure this address so that it accepts mails from Bugzilla only. Anything that is not coming from Bugzilla would be bounced back to the sender.

I think everyone keeps suggesting this for quite some time already but we need Yosh to implement this suggestion...

Done. But if anyone is filtering on the X-Mailing-List, you'll have to change it (this is something I wanted to avoid doing, but I haven't figured out how, so hence the wait)

-Yosh

On Tue, Aug 19, 2003 at 03:02:18PM -0700, Manish Singh wrote:

Done.

Damn, you were too fast :) Thanks for implementing it!

Daniel Egger writes:

Am Die, 2003-08-19 um 02.31 schrieb Sven Neumann:

(...)

Actually it was Mitch's idea. Perhaps he should continue to explain it then.

Exactly, why are you bothering me with an example?

Here we go (ignoring the rest of the thread)...

It all starts with the uglyness of the current implementation. Whenever we specify a help page in the current codebase, we have to write something like:

gimp_dialog_new (..., "dialogs/file_new.html", ...);

This is absolutely unmaintainable since it spreads the knowledge about where to find help pages across the whole source code. Apart from that, it's simply ugly. Even worse, it's my own fault from pre 1.2 days and I feel like I have to fix that ;)

To keep it simple and straightforward, I'd like to replace that with:

gimp_dialog_new (..., GIMP_HELP_FILE_NEW, ...);

and have these constants defined in one header file. The advantage of this approach is that we keep all available help topics in one place and that the compiler will not like unavailable help topics, so we can't suffer from typos like in the current implementation.

The header would look like:

#define GIMP_HELP_FILE_NEW "gimp-file-new" #define GIMP_HELP_FILE_OPEN "gimp-file-open" #define GIMP_HELP_IMAGE_FLATTEN "gimp-image-flatten"

etc...

For a smooth transition the first step would be to have:

#define GIMP_HELP_FILE_NEW "dialogs/file_new.html"

so we can collect needed help items without breaking the current system (which is already broken but still kindof works if you badly symlink aroung)

That's basically everything that needs to be changed in the core.

The help browser however still needs to find the actual help pages so there needs to be a mapping from these string IDs to links of some sort for finding the content (like relative paths or uris to html pages).

That mapping would preferably be a XML file like:

I don't care about the element names and stuff, it should just be simple enough to keep a GMarkup based parser simple too.

How should this XML file be generated? I suggest to simply use the same IDs as section IDs in the XML source so the mapping file can be generated automatically.

I also thought about generating the header which defines the help items, but gimp would depend on gimp-help or vice versa then, which is probably a bad idea. Also, manually syncing the gimp's and gimp-help's ID space will make us look at it more often, which can't be bad ;)

The generated mapping file would be installed under a defined name (like gimp-help.xml) and the help browser would parse it when it first opens a given help tree.

This approach also covers 3rd party plug-ins since they can tell the gimp where their help tree is. The help browser has access to this path and can simply open the gimp-help.xml file from that given help path.

All that needs to be done from the help system's side is generating this mapping file and installing it in the top help dir.

I will add the header mentioned above tomorrow and start adding items to it, so we can see all needed help items in one place (using the approach above).

Is this a solution everybody can live with or did I miss something obvious? If it sounds reasonable, we should go ahead, it's not even an awful lot of work (the coding part, not writing the help pages :)

ciao, --mitch

Am Mit, 2003-08-20 um 00.47 schrieb Michael Natterer:

Is this a solution everybody can live with or did I miss something obvious? If it sounds reasonable, we should go ahead, it's not even an awful lot of work (the coding part, not writing the help pages :)

Clean, (relatively) simple, I like it. In fact to push forward I simply went ahead and implemented it. Below is the result from the current German version. A few tweaks surely will have to be made and we haven't settled for some directory structure as of yet, but you get the idea....

Daniel Egger writes:

Am Mit, 2003-08-20 um 00.47 schrieb Michael Natterer:

Is this a solution everybody can live with or did I miss something obvious? If it sounds reasonable, we should go ahead, it's not even an awful lot of work (the coding part, not writing the help pages :)

Clean, (relatively) simple, I like it. In fact to push forward I simply went ahead and implemented it. Below is the result from the current German version. A few tweaks surely will have to be made and we haven't settled for some directory structure as of yet, but you get the idea....

Wow, that was fast :)

for completeness, this morning's discussion with roman on #gimp:

romanofski: i started that header, and we get *so*many* help items that i feel gimp-help should use a namespace at least similar to gimp, or we will get lost totally romanofski: like toolbox-rectangle-selection -> gimp-tools-rect-select heh ... you mean namespaces for filters, dialogs or specially the toolbox? romanofski: for everything
yeh
gimp-category-item
gimp-layers-new
gimp-layers-merge-down
etc.
and it looks we need a catrgory for each dialog like:
gimp-brushes-edit
gimp-brushes-refresh
gimp-brush-editor-foo
hm.. wait.. let me guess..
gimp-brush-editor-bar
gimp-preferences
gimp-preferences-interface
what do you think?
no.. i was thinking about it
and yes..
but i think this will not a problem yea
just a new attribute for this *.xml file the problem i see if we don't do it is that we will get lost in the two identifier namespaces maybe something like that?
why a new one, i thought this would be yes... and if someone will provide another help for his plugin ... why not the section ids which are already there? then he will install it separately and can use whatever namespace he likes he can even use the same ones, they live in a different mapping file yeh - okey.. so you mean, only renaming the section ids will do the trick yeh? yes
k
very nice
i'll do that
let me do that evil file first, so we can see what's needed oh.. okey
will be done today
cool
drop me a line if this works
looks we get this rolling now :)

I think that dialog covered the remaining questions...

ciao, --mitch

Am Mit, 2003-08-20 um 11.19 schrieb Michael Natterer:

Wow, that was fast :)

for completeness, this morning's discussion with roman on #gimp:

Wow, this is going to be a lot of typing overhead... ;)

What about we do the prefixing when we settled for a naming convention (do we have one already? Pointers?) so we don't have to do the renaming twice, since we also need to fix up the crossreferences?

On Wed, Aug 27, 2003 at 11:33:50AM +0200, Sven Neumann wrote:

Let's call each help-tree, either installed by gimp-help or by a plug-in, a help domain. The problem I see is that the current proposal doesn't define a way to link between help domains. While for example the freetype plug-in might install it's own help file(s), there is no way for the author of the text-tool help to link to this page and the freetype help author cannot link to the text tool documentation.

This problem could be solved by allowing links in the help pages to point to the registered identifiers instead of pointing directly to HTML pages. So when the text-tool help wants to link to the move-tool, it would use something like

and the help-browser would have to use it's mapping file to find the HTML page from the identifier.

This is a good way to share content. I mean - if i'm writing about the text tool, i dont need to write about hinting, font shapes and anything specific about fonts, i can point the user for more information to e.g. freetype.
Okey - background information is a part for the glossary.

For example, if i would need some help about a text tool, i'll get a short help if i use F1. Okey... maybe then, i want to read any further, because fonts are interesting and this stuff about freetype also.

The worst case is, if there is no freetype plugin installed, the help will not be available. So - if i link to other help pages, the help browser or the background "logic" has to decide if the help is available or not. If the help isn't there, the link shouldn't be displayed, because the reader couldn't get the information which is offered. Is it possible and not to hard to implement such things?

A second thing is, how fast can the available help docs be parsed. If i understood you right, the helpbrowser also knows other references. If the user want a short help, the help browser parses these xml files and go straight forward to the subject (or display an error - not yet written). But if the helpbrowser needs to parse references and needs to decide things (is this help available or not), will it take to much time to display the short help item?

Greetings,

On 27 Aug 2003 11:33:50 +0200, Sven Neumann wrote: [...]

This problem could be solved by allowing links in the help pages to point to the registered identifiers instead of pointing directly to HTML pages. So when the text-tool help wants to link to the move-tool, it would use something like

and the help-browser would have to use it's mapping file to find the HTML page from the identifier.

The problem with this solution is that it will prevent the help system from ever working in a standard browser. Wouldn't it be better to pre-process all files at build time or installation time and generate standard XHTML? If this is done at installation time, we could write a tool that updates the cross-references as necessary (this "we" could be me, if nobody else is interested).

As a last note, let me outline a small error in the proposal I just made. Since is not part of XHTML, we should check if there's an element we can (ab)use or we need to introduce a namespace for the link element (or whatever it would be called).

Well, is part of XHTML, but it is only allowed inside . If you want to add a cross-reference, the best element to choose would be , even if you use it with non-standard attributes.

-Raphaël

Am Mit, 2003-08-27 um 11.33 schrieb Sven Neumann:

Any help page could then refer to the freetype plug-in by using

As you can see, the namespace prefix is irrelevant, we can choose "ft:" here to keep the notation short. Of course if multiple links to the freetype plug-in are needed, the namespace can be declard in the top-level element and the link would simply become

I am not sure how much work is needed to teach the help-browser about a new link type and XML namespaces but I think it might be worth the effort. This architecture should allow us to do some nifty stuff and it will assure that no conflicts will ever arise from help registered by third-party plug-ins.

You possibly also though about how to generate these? It's not just about introducing a new tag to XHTML but somehow you also need to express these in the DocBook source.

At the moment I don't see how this could even remotely work as there's simply no way to express relative links which are not resolved at latest at transformation time. There is a way to arbitrarily map references using an external map (which can be autogenerated from DocBook source and I'm actually abusing to generate the mapping for the helpbrowser) however this means:
a) the documentation has to be in DocBook (or a new mapper has to be made somehow which could be tricky at least for say HTML directly) b) all referenced documentation has to be know when the docs are transformed which is impossible for obvious reasons.

My proposal would also allow to split the help between the GIMP core and the plug-ins we ship with GIMP. Just as we do for i18n now, where there are translation domains for the core, the plug-ins and script-fu, there could be help domains for the core, the standard plug-ins and individual domains for Script-Fu, Python and Perl scripts.

Nice idea but tricky to impossible to get right. This map to anything proposal will *only* work if you have some means to do the transformation online (which I'm not opposed to but you are) *or* someone has to teach the helpbrowser about those mappings *and* special crappery has to be installed to not make the XSLT processor barf and produce the "right" results.

I'm absolutely against the idea of generating invalid XHTML (read: I will not do this). If this is the way to go it has to be representable in valid XHTML.