Re: [Gimp-developer] gimp, docbook or apple trees, fruit or seeds
On Thu, 2003-07-24 at 02:07, Daniel Egger wrote: But this it what it looks like after the transformation: [EMAIL PROTECTED]:/devel/gimp-help-2/help/C/plainhtml$ ls ch01.html ch03s04.html ch03s09.html ch03s14.html gimp-help-plain.css ch02.html ch03s05.html ch03s10.html ch03s15.html go01.html ch03.html ch03s06.html ch03s11.html ch03s16.html index.html ch03s02.html ch03s07.html ch03s12.html ch04.html ch03s03.html ch03s08.html ch03s13.html ch04s02.html I remember using something like the following to use the ids as filenames once: (define %use-id-as-filename% #t) The help browser could then check if the id as requested by the GIMP exists and if not, it could show a default page asking the user to write up some documentation. Don't know if that helps... Just an idea. Sincerely, ./Brix -- Henrik Brix Andersen [EMAIL PROTECTED] ___ Gimp-developer mailing list [EMAIL PROTECTED] http://lists.xcf.berkeley.edu/mailman/listinfo/gimp-developer
Re: [Gimp-developer] gimp, docbook or apple trees, fruit or seeds
Am Die, 2003-07-29 um 00.07 schrieb Henrik Brix Andersen: I remember using something like the following to use the ids as filenames once: (define %use-id-as-filename% #t) Yeah, this is what we did years back with DocBook/SGML and DSSSL stylesheets. :) The help browser could then check if the id as requested by the GIMP exists and if not, it could show a default page asking the user to write up some documentation. This was really a PITA to use because we had no control over the generated files. -- Servus, Daniel signature.asc Description: Dies ist ein digital signierter Nachrichtenteil
Re: [Gimp-developer] gimp, docbook or apple trees, fruit or seeds
Am Don, 2003-07-24 um 11.01 schrieb Sven Neumann: Even gimp-1.2 can link to anchors already. There is no need for toplevel HTML files for each and every help topic that should be reachable by pressing F1. In theory, the whole help could be in a single file. That would of course not be useful but any granularity should be doable using anchors. This is possible, but using anchors in a file means that last time I looked you cannot render a notice that the help is not available because the help browser would load the file and then jump to the beginning of the document when the anchor doesn't exist. Also it's not good for the user experience when you press F1 on some tool and get a 50 pages document explaining all tools at once, even when the display starts at the right position within the 50 pages. Not to mention that one will need gobs of memory to render such documents because of all the images we already have or intend to have. But yes, giving up granularity to ease maintainance is possible but more like a quick hack than a real solution. I really detest hacks when not doing them for myself because it makes one look rather foolish. -- Servus, Daniel signature.asc Description: Dies ist ein digital signierter Nachrichtenteil
Re: [Gimp-developer] gimp, docbook or apple trees, fruit or seeds
Hi, Daniel Egger [EMAIL PROTECTED] writes: This is possible, but using anchors in a file means that last time I looked you cannot render a notice that the help is not available because the help browser would load the file and then jump to the beginning of the document when the anchor doesn't exist. The help-browser behaviour for non-existant anchors could probably be changed. I'd have to look into the GtkHTML2 API to give a more definite answer but I think it should be doable. Also it's not good for the user experience when you press F1 on some tool and get a 50 pages document explaining all tools at once, even when the display starts at the right position within the 50 pages. Not to mention that one will need gobs of memory to render such documents because of all the images we already have or intend to have. Noone said we have to use a single file only. But yes, giving up granularity to ease maintainance is possible but more like a quick hack than a real solution. I really detest hacks when not doing them for myself because it makes one look rather foolish. Now I am finally sure that I still don't have the slightest idea of the problems you see and what you imagine as the solution. Would you mind to explain it for me again? In the meantime, I will try to outline the system I am imagining. We would remove all the hardcoded HTML filenames from GIMP and replace them with unique and meaningful identifiers like for example gimp-file-new-dialog. The help files would be written in DocBook/XML and we would assign the same ids as id attributes to the associated content. The DocBook/XML files are then converted to a reasonably fine-grained set of XHTML files and the XSLT processor creates an additional XML file that holds a mapping from id to filenames. Of course multiple ids may point to the same file. The GIMP helpbrowser is then passed the id, it reads the mapping table and loads the HTML file that contains the anchor with the requested id. If the XML file doesn't list the requested id, the help-browser can display a standard page that explains that help for this subject is missing. Sven ___ Gimp-developer mailing list [EMAIL PROTECTED] http://lists.xcf.berkeley.edu/mailman/listinfo/gimp-developer
Re: [Gimp-developer] gimp, docbook or apple trees, fruit or seeds
Am Don, 2003-07-24 um 15.37 schrieb Sven Neumann: The help-browser behaviour for non-existant anchors could probably be changed. I'd have to look into the GtkHTML2 API to give a more definite answer but I think it should be doable. It would be great if you could look it up because this is a real must. Noone said we have to use a single file only. I'm not talking about a single file either but about a file per chapter since we cannot change the granularity at will. Now I am finally sure that I still don't have the slightest idea of the problems you see and what you imagine as the solution. Would you mind to explain it for me again? Since my imagined solution would require efforts which are not handable for the shortterm release let us rather focus on you idea and live with the additional maintainace efforts and less user comfort for now. In the meantime, I will try to outline the system I am imagining. We would remove all the hardcoded HTML filenames from GIMP and replace them with unique and meaningful identifiers like for example gimp-file-new-dialog. The help files would be written in DocBook/XML and we would assign the same ids as id attributes to the associated content. Check. The DocBook/XML files are then converted to a reasonably fine-grained set of XHTML files and the XSLT processor creates an additional XML file that holds a mapping from id to filenames. Okay, so the filenames do not matter anymore and we can use automatically generated ideas instead of forcing the XSLT processor to generate a specific set. This is a big plus over the current situation. But how do we generate the mapping file? Since we rely on the docbookxsl stylesheets they would have to output the mapping right after they wrote the transformed output or remember the ids and output at the end. I do not know whether they have this feature and need to check the current situation. If they don't provide this feature (which is quite likely) we'll really have a hard time, because we'll either have to override all transformations to get the recording and output done or we'll have to simulate the automatic generation of filenames in a to-be-written standalone XSLT file to replay the generation of HTML files thus knowing the filenames. But let me look it up first before we worry about how we get it done... Of course multiple ids may point to the same file. The GIMP helpbrowser is then passed the id, it reads the mapping table and loads the HTML file that contains the anchor with the requested id. If the XML file doesn't list the requested id, the help-browser can display a standard page that explains that help for this subject is missing. Check. -- Servus, Daniel signature.asc Description: Dies ist ein digital signierter Nachrichtenteil
Re: [Gimp-developer] gimp, docbook or apple trees, fruit or seeds
Hi, Daniel Egger [EMAIL PROTECTED] writes: The help-browser behaviour for non-existant anchors could probably be changed. I'd have to look into the GtkHTML2 API to give a more definite answer but I think it should be doable. It would be great if you could look it up because this is a real must. The API has html_document_find_anchor() which seems to fit our needs just perfectly. Sven ___ Gimp-developer mailing list [EMAIL PROTECTED] http://lists.xcf.berkeley.edu/mailman/listinfo/gimp-developer
Re: [Gimp-developer] gimp, docbook or apple trees, fruit or seeds
Hi, Carol Spears [EMAIL PROTECTED] writes: you and I are scheduled to discuss this after camp. if you continue to insist to reply to my mail, i will continue to insist that you stick to *your* scheduled time for this discussion. I said that I want to wait till after the camp before I take a closer look at the XML format for plug-in infos that you are designing. This seems to be definitely a post-2.0 thing and if you need me to look at it, it will have to wait a bit. The format we use for writing our help pages is a completely different topic and I would welcome if you would try to keep them distinct. If I am wrong about this being a different topic, this may be because you never explained what you are actually doing with this plug-ins XML file that you are working on. Sven ___ Gimp-developer mailing list [EMAIL PROTECTED] http://lists.xcf.berkeley.edu/mailman/listinfo/gimp-developer
Re: [Gimp-developer] gimp, docbook or apple trees, fruit or seeds
David Neary wrote: Carol Spears wrote: Daniel Egger wrote: DocBook was written exactly for the purpose we need. as much as i love gimp, i wonder if someone got their rent paid from netscape.com for making that my choice regardless. With everything else being so sensible in gimp, how come i did not get a choice that included lynx or the awesome w3m? did you know w3m renders images on xterms lately? that means it could render any screenshots gimp gets of itself for its help docs. Actually, I'm not sure I see the benefits in not having html as the primary format... Sure, we could go for a format which allows multi-node searching (like info only better), but html docs would have the added benefit of not needing to be local and still being usable. And the user gets to choose what help client they use. And most people have a browser open all the time anyway. I'm not saying that a custom help browser is a waste of time - but do we have the time to do it? Surely starting with docbook or whatever and marking it up to html, with the possibility of doing funkier stuff later, allows us to have something, quickly? Cheers, Dave. my layout is aimed first at html and second at LaTeX. I want a choice of browsers. I think it is easy to make a plugin that calls from a list of available browsers. i think this discussion is really stupid. you could actually tuck the source code to the w3m with the image rendering ability into the documentation and probably no one would know the difference sizewise, especially if you insist on all those stupid levels of tags in the layout. but it is easy for gimp to find the browsers i have installed and add them to a menu. so i really am not going to be following this thread anymore. thanks for the time and thought you all spend writing this crap to the list. carol ___ Gimp-developer mailing list [EMAIL PROTECTED] http://lists.xcf.berkeley.edu/mailman/listinfo/gimp-developer
Re: [Gimp-developer] gimp, docbook or apple trees, fruit or seeds
Am Die, 2003-07-22 um 21.57 schrieb David Neary: Actually, I'm not sure I see the benefits in not having html as the primary format... Sure, we could go for a format which allows multi-node searching (like info only better), but html docs would have the added benefit of not needing to be local and still being usable. What do you mean by not needing to be local? The problem is exactly that the filenames have to be known in advance so we can link to them; this means that for HTML the files have to be in a known place (defined at compile time) and there has to be a mapping. And the user gets to choose what help client they use. There's no problem at all using a normal browser to read the full docs in HTML format. It simply doesn't make a whole lot of sense to me trying to remote control a browser to feed it with correct links while at the same time having the problems that - a webbrowser is by design not the optimal tool to view online help while working with the application - a webbrowser cannot provide fulltext search over all documentation since it doesn't see the whole text at once I'm not saying that a custom help browser is a waste of time - but do we have the time to do it? Surely starting with docbook or whatever and marking it up to html, with the possibility of doing funkier stuff later, allows us to have something, quickly? That's exactly my point. Sorry to be negative here but I have the very strong feeling that we will not get gimp-help-2 into adequate shape until the projected date of release of GIMP 2.0 and as such it doesn't make a whole lot of sense to me to bend over trying to somehow get the transformation and the help-browser in place because it's a waste of precious time when not knowing that it'll be used for a longer period of time. The explanation I proviced about displaying HTML instead of DocBook directly (still just for the online help!) should show why this an inferior solution. I've a few more points in case someone wants to discuss it over, but for me there's no point in supporting a quick hack instead of a proper long term solution which the HTML one simply cannot be, at least not in this form, and I haven't heard of a better one yet. -- Servus, Daniel signature.asc Description: Dies ist ein digital signierter Nachrichtenteil
Re: [Gimp-developer] gimp, docbook or apple trees, fruit or seeds
Am Die, 2003-07-22 um 21.03 schrieb Sven Neumann: usually need a small subset only. I am sure that people who want to contribute documentation can learn the necessary bits pretty fast. Or even better: Don't need to... -- Servus, Daniel signature.asc Description: Dies ist ein digital signierter Nachrichtenteil
Re: [Gimp-developer] gimp, docbook or apple trees, fruit or seeds
Hi, Daniel Egger [EMAIL PROTECTED] writes: That's exactly my point. Sorry to be negative here but I have the very strong feeling that we will not get gimp-help-2 into adequate shape until the projected date of release of GIMP 2.0 and as such it doesn't make a whole lot of sense to me to bend over trying to somehow get the transformation and the help-browser in place because it's a waste of precious time when not knowing that it'll be used for a longer period of time. I think we could get the framework done for 2.0 and fill in the content when 2.0 is out. The help files are supposed to be distributed separately anway so I don't see the long period of time you are speaking of. The explanation I proviced about displaying HTML instead of DocBook directly (still just for the online help!) should show why this an inferior solution. I've a few more points in case someone wants to discuss it over, but for me there's no point in supporting a quick hack instead of a proper long term solution which the HTML one simply cannot be, at least not in this form, and I haven't heard of a better one yet. I tried to outline one. Should I try to explain it again? Sven ___ Gimp-developer mailing list [EMAIL PROTECTED] http://lists.xcf.berkeley.edu/mailman/listinfo/gimp-developer
Re: [Gimp-developer] gimp, docbook or apple trees, fruit or seeds
Sven Neumann wrote: Hi, Carol Spears [EMAIL PROTECTED] writes: you and I are scheduled to discuss this after camp. if you continue to insist to reply to my mail, i will continue to insist that you stick to *your* scheduled time for this discussion. I said that I want to wait till after the camp before I take a closer look at the XML format for plug-in infos that you are designing. This seems to be definitely a post-2.0 thing and if you need me to look at it, it will have to wait a bit. The format we use for writing our help pages is a completely different topic and I would welcome if you would try to keep them distinct. If I am wrong about this being a different topic, this may be because you never explained what you are actually doing with this plug-ins XML file that you are working on. are you begging to change your scheduled time to discuss this with me? i am really so busy. carol ___ Gimp-developer mailing list [EMAIL PROTECTED] http://lists.xcf.berkeley.edu/mailman/listinfo/gimp-developer
Re: [Gimp-developer] gimp, docbook or apple trees, fruit or seeds
Daniel Egger wrote: Am Die, 2003-07-22 um 21.57 schrieb David Neary: Actually, I'm not sure I see the benefits in not having html as the primary format... Sure, we could go for a format which allows multi-node searching (like info only better), but html docs would have the added benefit of not needing to be local and still being usable. What do you mean by not needing to be local? The problem is exactly that the filenames have to be known in advance so we can link to them; this means that for HTML the files have to be in a known place (defined at compile time) and there has to be a mapping. I may be missing the point, but if you use relative paths for linking, there wouldn't be a problem, would there? In any case, I bow to your greater knowledge :) I really know very little about documentation mark-up. - a webbrowser is by design not the optimal tool to view online help while working with the application - a webbrowser cannot provide fulltext search over all documentation since it doesn't see the whole text at once I understood that docbook2html xslt was out there, and that there were utilities that did docbook to pdf, html or text fairly easily. until the projected date of release of GIMP 2.0 and as such it doesn't make a whole lot of sense to me to bend over trying to somehow get the transformation and the help-browser in place because it's a waste of precious time when not knowing that it'll be used for a longer period of time. The explanation I proviced about displaying HTML instead of DocBook directly (still just for the online help!) should show why this an inferior solution. I've a few more points in case someone wants to discuss it over, but for me there's no point in supporting a quick hack instead of a proper long term solution which the HTML one simply cannot be, at least not in this form, and I haven't heard of a better one yet. It's clear that I don't understand the problems involved, so as I said before, as far as deployment goes, I bow to your better judgement. Cheers, Dave. -- David Neary, Lyon, France E-Mail: [EMAIL PROTECTED] pgp0.pgp Description: PGP signature
Re: [Gimp-developer] gimp, docbook or apple trees, fruit or seeds
Hi, can we please try to avoid a flamewar about DocBook here. All our help is in DocBook, it is a well established format for this purpose. I admit that it can be quite complex but it is well documented and you usually need a small subset only. I am sure that people who want to contribute documentation can learn the necessary bits pretty fast. There are stylesheets available for transformations to all sort of formats suited for online or print publishing. IMHO it doesn't help to question the use of DocBook. There are some decisions about gimp-help that need to be made, the format for the docs is not one of them. Sven ___ Gimp-developer mailing list [EMAIL PROTECTED] http://lists.xcf.berkeley.edu/mailman/listinfo/gimp-developer
Re: [Gimp-developer] gimp, docbook or apple trees, fruit or seeds
Carol Spears wrote: Daniel Egger wrote: DocBook was written exactly for the purpose we need. as much as i love gimp, i wonder if someone got their rent paid from netscape.com for making that my choice regardless. With everything else being so sensible in gimp, how come i did not get a choice that included lynx or the awesome w3m? did you know w3m renders images on xterms lately? that means it could render any screenshots gimp gets of itself for its help docs. Actually, I'm not sure I see the benefits in not having html as the primary format... Sure, we could go for a format which allows multi-node searching (like info only better), but html docs would have the added benefit of not needing to be local and still being usable. And the user gets to choose what help client they use. And most people have a browser open all the time anyway. I'm not saying that a custom help browser is a waste of time - but do we have the time to do it? Surely starting with docbook or whatever and marking it up to html, with the possibility of doing funkier stuff later, allows us to have something, quickly? Cheers, Dave. -- David Neary, Lyon, France E-Mail: [EMAIL PROTECTED] ___ Gimp-developer mailing list [EMAIL PROTECTED] http://lists.xcf.berkeley.edu/mailman/listinfo/gimp-developer