Am Mon, 2003-07-21 um 20.09 schrieb Sven Neumann:

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

Are we talking about online help or a manual?

>  I do think that using (some flavour of) HTML has a lot advantanges.

Not as far as I can see, this is exactly the reason every OS has it's
own metaformat for online help (think of CFM, Mac Doc Ressources, man
pages, info, or even DocBook/XML in case of GNOME and KDE).

>  The biggest advantage is that we can expect a working
> browser on almost every box that GIMP gets installed to.

But a browser doesn't necessarily sport the navigation features one
would like to have, or a global find function. Also a browser is meant
for viewing documents on the whole screen while a help browser is
typically used concurrently to the application it tries to help the 
user with.

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


Um, I seriously think I should rephrase the problem as we're talking
about very things here.

> Sorry, but I haven't yet understood the problem with filenames you see
> nor did I understand how your proposal would avoid it.

I'm not mapping filenames (neither XML nor HTML) but entities and or ids
in XML files wherever they might appear. Basically one can add id
attributes to arbitrary tags and use them as crossreference or link
targets. So if you have one file referencing all other files (in the
gimp-help module) specifying entities and then you call those entities
a processor can cache the skeleton of the whole documentation tree and
have all ids in memory thereby knowing where the specified (in GIMP
source) id can be found in the jungle of XML files. This way I can
(re-)structure information however I like and they will be always found.

OTOH using filenames which are loaded means that one has to teach the
XML processor exactly how the *output* are to be named which is a
feature which:
a) not all XSLT-processors support
b) works only with a fixed structure because the layout (chapters,
   sections, paragraphs) determine where the content will be located;
   the choosable filename (in the XML files) is a hint at best where
   it should place the HTML files.

>  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)?

When I say XML in the context of gimp-help I always mean DocBook/XML 
which refers to the *input* format.

> We ran a link-checker through the help files so I am pretty sure there
> isn't.

Huh? Where did you get that one from? (No, I wasn't talking about the
links in the HTML files, but the links from the GIMP to the HTML files).

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

I understand but still think that using that unique identifiers directly
on the XML files is more wise.

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

Sorry, my bad, entities are used to teach a parent document about it's
childs; linking is done using ids on arbitrary tags. 

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

Have you ever tried yelp? If not, please do it...


Attachment: signature.asc
Description: Dies ist ein digital signierter Nachrichtenteil

Reply via email to