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

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.

Am Die, 2003-07-22 um 20.47 schrieb Carol Spears:

I tried to work with simple docbook, docbook, website docbook. I don't know how recent your gimp download is but this format is nothing like gimp since gimp-1.0.2. I have to stretch my imagination so much to make the format fit the gimp.

How so?

I was actually going to try to substitute for . Do you know how deeply the email string is nested in any docbook?

Yes, I know but this is for a purpose. You could also put this information (except it's mandantory) in a normal paragraph; however you don't have the type information in the transformation process later in case you could make some use of it -- like print the Author's name (without emailaddress) on the bottom of every page in the document.

trust me and my recent experience, docbook was not written at all with gimp in mind.

It was written with documentation in mind which is exactly what we need; I wouldn't use it as a fileformat for images at all.

for instance, it is obvious to me that the docbook people could not imagine an app that can take its own screenshots.

They didn't design this (because it *IS* overkill) but you can certainly express it using the given hooks.

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.

I cannot imagine how this auto-screenshot feature is supposed to work; but given that one can do anything within the bounds of imagination and knowledge I cannot see why it wouldn't....

i hate to limit the scope and imagination though, by being so disgusted with the docbook* set up.

I can write up a installation documentation for docbook + compilation of xsltproc in less that 10 comprehensible lines... Remember we're not talking about DocBook/SGML anywork -- that's a disgusting piece of work.

daniel, do you have something to attach to an email? like i did?

What did you have in mind?

no this is what happened. i tried to help, asked a few questions about the logic of the template and what the tags were *supposed* to mean, and syngin decided it was quicker and easier to write the documentation without help.

The tags are selfexplanatory, the meaning of them is nicely covered (with examples) in the DocBook-book (the "duck book"). We're not *requiring* any of them execept the structural ones (sects, paras, chapters) however: the more the better.

but i would like to be extremely clear about this. i am not going to waste my time contributing to docbook formated information. however, if you insist on setting the document writers up with that terrible template system again, i should be able to use the information anyways as a thoughtfully written xslt can over look the bad logic and find information there anyways. So what ever *you* commit, i can use.

See, I already offered to take content in *any* and enrich it using the appropriate tags. Why? Because I'm not an good content writer because I'm not creative enough. I know how to deal with DocBook, XML and XSLT pretty well though.

Again: If you want to write, *do it*, send it to me *in any format convenient for you* and I will merge the pieces. And believe me that I won't say it another time because I'm starting to get sick of people who claim wanting to write docs but at the same time complain about the format and thus have a poor excuse why they cannot....

also, we don't need the tree or the fruit of docbook, it is huge and the format is not good for gimp.

Okay, propose a better (XML-) format, write a DTD (yet better also a Schema) *and* XSLT transformation into at least (X)HTML and PDF and I'll call it a deal. Just tell me how long you need...

Hi,

Carol Spears 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

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...

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.

Hi,

Daniel Egger 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

Am Mit, 2003-07-23 um 16.41 schrieb Carol Spears:

[ mail stripped down to points that haven't been answered a gazillion times... ]

a layout and dtd made for gimp by people who use gimp and need for gimp to document itself and such would be useful for many many applications, i guess.

Don't guess, do it! It's an awful lot of work and needs experienced people who can design a DTD for such a complex application, write it down in the correct syntax and last but not least one needs transformations otherwise all that can be done is walking in the trees...

i am sick of working with choices that were not made for me.

where is syngin, btw. you write this as a layout designer.

I'm no layout designer, I just have some "real-life" experience in building documentation systems.

i think syngin is depressed and gone. i am so sorry about that. i blame docbook and sgml layouts for this, unless i hear something else about it.

Mel worked with me quite a lot on the docs and he never signalled any signs of unsolvable problems. Also he did all the files he commited all on his own and surprised me quite a few times with high quality DocBook sources, not just in content but especially in markup!

your hearsay about usage, my hearsay about being depressed and quitting.

I've instructed more than 10 people in DocBook. No one ever complained.

okay. GNU/Image Manipulation Program. gimp can write most of this stuff himself.

Interesting. How come I didn't notice? :) What are you talking about?

i think i needed more coffee when i wrote this. actually, the screenshots should be easy with gimp, but not with gimp-1.2. i made the unfortunate mistake of starting the mmmaybe resource images with the palettes. palettes don't go to the pdb that way for gimp-1.2. neither do gimp-impressionist resources. i got discouraged.

???

cool. you will then proceed to author the information and tell others how to author it? awesome!

Sure.

will you forward all the mail if whatever "information scooper" interested parties use doesn't scoop from information that deeply nested?

Sorry, sometimes I really have trouble parsing your sentences...

i have not really had a chance to look to what is required and not required in that twisted mess (docbook).

Get the DocBook book from the internet, check it online or even buy the book if you prefer it in printed form. It'll tell you how to do the stuff you want to do and what is required for it to work *including* examples.

See, I already offered to take content in *any* and enrich it using the appropriate tags. Why? Because I'm not an good content writer because I'm not creative enough. I know how to deal with DocBook, XML and XSLT pretty well though.

this tells me that you would have no problem skipping docbook. it is an unnecessary step.

It's NOT! XML alone won't let you do dick, you need a DTD which gives it a meaning and this is DocBook in our case. I wouldn't have a problem with any other DTD but you have failed to show me one which provides: a) all documentation facilities we need b) corresponding XSLT stylesheets

In fact you just claimed it would be easy to design a designated DTD just for GIMP documentation but so far haven't backupped this claim.

my format is posted publically. i am scheduled to discuss it after camp. i am thinking about scheduling Neditcon1 for the same week, i dunno yet.

You're going to Berlin? Maybe I can stop by for a few hours since I'll probably be in town this week.

you can look at that and comment.

I'd like to, where did you say can one pick it up?

please, do not start this shit on the gimp-user list!

I will ask on the gimp-users list for volunteers to write DocBook documentation (actually because I've been asked to do so). This thread here never was intended as a flamewar I still don't see it as one; a lot of FUD and unfounded information was spread in a thread that started (and still continues) as a quite informative one. Set your facts straight or simply back up and this will be forgotten.

Am Mit, 2003-07-23 um 18.17 schrieb Sven Neumann:

I think we could get the framework done for 2.0 and fill in the content when 2.0 is out.

Ok, this sounds like a plan; I'm not entirely happy but after all this is not the only of our goals... :)

The help files are supposed to be distributed separately anway so I don't see the long period of time you are speaking of.

Distributed seperately? Good idea, however that means that someone has to do releases....

I tried to outline one. Should I try to explain it again?

Hold on, if it's in the long mail I haven't answered yet then I'll probably get to it this afternoon and maybe I can get an idea of whether there's a chance it'll work.

If it might work then we should go for the (in my eyes) unsatisfactory hack, if I can imagine problems we'll have to discuss a bit more or you show us your proof of concept. :)

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.

Am Mit, 2003-07-23 um 22.35 schrieb David Neary:

I may be missing the point, but if you use relative paths for linking, there wouldn't be a problem, would there?

There is, because I still need to know the filenames somehow. Setting up a mapping topic->HTML file for GIMP is not elegant but doable (in fact that's what GIMP 1.2 does in source), the bigger problem is to get the xsltprocessor to spit out little chunks of documentation with the correct filename. I can only setup the granularity and provide filenames which are more treated like hints, means: I say, give this chapter the filename foo.html and the subsections the names bar.html and baz.html and it'll go creating one file foo.html with the content of bar.html and baz.html but not those files.

Note: This is not the only thing that can happen wrt to the generated files, and exactly the reason why I reorganized the whole old helps' structure to match the desired filesystem layout which is not only a pain in the ass to maintain and setup but also überugly to read. Still the old help is missing a few files which are there but have a different than expected name and thus cannot be found by the helpbrowser; also there's some really nasty link/copy/rename action involved at "compile time"...

The new docs are designed around a natural reading to ressemble a normal style manual which can be used as an online help as well. Though to get usable results without bending around some filenames we need to directly navigate to the desired point using canonicalized ids. This is AFAIR only possible by doing something similar to yelp, i.e. using a DOM to navigate directly to ids and render exactly the named element including all subelements.

In any case, I bow to your greater knowledge :) I really know very little about documentation mark-up.

This is really not about mark-up but about transformation. :)

I understood that docbook2html xslt was out there, and that there were utilities that did docbook to pdf, html or text fairly easily.

The transformation is no problem, like xsltproc --nonet stylesheets/plainhtml.xsl gimp.xml and it'll create a directly placing all HTML files.

But this it what it looks like after the transformation:

egger@sonja:/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

Now try to map that mess to something sensible in the GIMP. Consider that I can change the name of either all ch[0-9]+.html *or* ch[0-9]+s[0-9]s.html to something more usable, but not both. Also the name of the glossary, which would be go01.html here is fixed. Changing the granularity would mean less files which would mean that all data is munched into fewer files resulting in even fewer targets to link to.

And I'm not even talking about navigation to the point here. The chapters will only contain a description of the chapter or even just links in case the author was lazy while the section files only contain the content of exactly that one section. If you want to have both because you'd like to link to a chapter (this can be transferred to any other structural element as well) you loose.

Hi,

Daniel Egger writes:

The new docs are designed around a natural reading to ressemble a normal style manual which can be used as an online help as well. Though to get usable results without bending around some filenames we need to directly navigate to the desired point using canonicalized ids. This is AFAIR only possible by doing something similar to yelp, i.e. using a DOM to navigate directly to ids and render exactly the named element including all subelements.

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.

Sven

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.

Hi,

Daniel Egger 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

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.

Hi,

Daniel Egger 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

On Thu, 2003-07-24 at 02:07, Daniel Egger wrote:

But this it what it looks like after the transformation:

egger@sonja:/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

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.