Re: [Gimp-developer] gimp, docbook or apple trees, fruit or seeds

2003-07-28 Thread Henrik Brix Andersen
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

2003-07-28 Thread Daniel Egger
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

2003-07-24 Thread Sven Neumann
Hi,

Daniel Egger [EMAIL PROTECTED] 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
___
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

2003-07-24 Thread Daniel Egger
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

2003-07-24 Thread Sven Neumann
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

2003-07-24 Thread Daniel Egger
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

2003-07-24 Thread Sven Neumann
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

2003-07-23 Thread Sven Neumann
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

2003-07-23 Thread Carol Spears
Sven Neumann wrote:

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.
 

absolutely.

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.
thanks for you consideration
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

2003-07-23 Thread Carol Spears
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

2003-07-23 Thread Daniel Egger
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

2003-07-23 Thread Daniel Egger
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

2003-07-23 Thread Sven Neumann
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

2003-07-23 Thread Daniel Egger
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. :)

-- 
Servus,
   Daniel


signature.asc
Description: Dies ist ein digital signierter Nachrichtenteil


Re: [Gimp-developer] gimp, docbook or apple trees, fruit or seeds

2003-07-23 Thread Carol Spears
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

2003-07-23 Thread David Neary
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

2003-07-22 Thread Sven Neumann
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

2003-07-22 Thread David Neary
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