docbook crossrefs

["Mathieu Lacage" <mathieu_lacage myrealbox com>]

hi all,

I have been trying to write some gnome developer top-level documentation. One crucial thing I need to do is to cross-ref multiple other docbook-based documents (the different api docs we have).

The question is: how can I write docbook which generates correct html links if it is translated to html by the help browser ? Is this possible without any G2-specific extension ? I don't rellay understand the ins and outs of the problem but I know what I want to do: I want to be able to click on the links when I cross-ref a function from my documentation and get the function's API doc be displayed by the application.

I also wonder if there is a specific application I should use to display developer documentation. I am not too excited by devhelp because it seems not to use native xml db as its source format and I'd like to ship users the xml and not any automatically-generated file.

Finally, it would make sense if we could provide users with a tool which can display dia files (and not pngs) in the document directly such that we don't have to ship pngs.

I know most of the points above are:
  - difficult if not impossible to implement
  - subject to endless discussions
but, as a doc writer, I'd like to know what the user experience will be when they read my doc and I'd like this experience to be as good as possible _and_ I'd like not to ship any automatically-generated file because it is always a pain to maintain.

I hope I won't generate too much hate-mail,

regards,
Mathieu