Daniel Egger <[EMAIL PROTECTED]> writes:

> Why not? Why should DocBook be more difficult to render than HTML? It
> doesn't necessarily have to be a DocBook renderer, it could also be a
> live translator. Maybe we can utilize yelp for it?

Because there are widgets that render HTML but no widgets that render
DocBook. And actually, who wants to use the help-browser to browse the
help files? I do think that using (some flavour of) HTML has a lot
advantanges. The biggest advantage is that we can expect a working
browser on almost every box that GIMP gets installed to.

> The problem is that once you created the HTML, it's fixed including
> the filenames because the links point to it. Getting <insert your
> favourite xslt processor here> to spit out HTML files with the
> "correct" names in the granularity we want is close to impossible; I
> had to reorder gimp-help quite a bit to make it possible at
> all. Your developer.gimp.org experience is probably limited to
> either one single HTML file or files whose names don't matter except
> for index.html.

That is not true. There is a simple XML file that maps the XML
filenames to HTML filenames:


Sorry, but I haven't yet understood the problem with filenames you see
nor did I understand how your proposal would avoid it. You would just
link to XML filenames, wouldn't you? How is that any better than
linking to HTML filenames (apart from the fact that I am speaking of
XHTML here, so that would be XML then anyway)?

> However at the moment we need the filenames because the help browser
> picks up the files by loading a prespecified path.  This scheme is
> not only hard to maintain but also broken by design; I'm quite
> confident there are still mislinked help files and we didn't notice
> in GIMP 1.2.

We ran a link-checker through the help files so I am pretty sure there
isn't. But of course we don't want to stick to the old system, that is
not the point. The idea was to make GIMP refer to unique identifiers
and to have a file that specifies how these identifiers map to HTML
filenames (and anchors into HTML pages).

>> > - The docs need to be kept in sync with the GIMP Source which is a
>> > tedious work.
>> How would your solution avoid this problem?
> Instead of specifying filenames in the GIMP XML entities are specified
> to reference the wanted section. So both the help internally AND the
> GIMP are using exactly the same mapping to the files thereby avoiding
> annoying synchronisation problems.

Eeek, entities are probably the worst thing in the XML / SGML world.
I would rather avoid them whenever possible. An entity is just a macro
and is thus mainly used for rather bad hacks.

> Also the documentation can be shipped *as is* without risking
> wreckage every time the stylesheets or the processor or the GIMP or
> the content changes.

I think we should ship the documentation including the generated HTML
pages. XSLT seems to be rather difficult to setup and I would not want
to put that burden on the users.

Gimp-developer mailing list

Reply via email to