Re: docbook crossrefs

[Mathieu Lacage <mathieu_lacage realmagic fr>]

Hi Malcolm, 

comments below 

On Mon, 2002-12-09 at 10:23, Malcolm Tredinnick wrote: 
[snip] 
> > 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.
> 
> Right at the moment, this is not possible. The initial problem you have
> is that you do not know where the API documentation is installed. The
> solution is probably to install an OMF file with each piece of API
> documentation and register it with scrollkeeper so that something like
> Yelp can find the document. That still leaves the problem of how to get
> Yelp to extract the right document, but let's cross one hurdle at a
> time.
I'd say the question is: what does the cross-ref look like in the source
document ? Is it a structured string which contains two parts: 
- target document 
- target item within document 

In which case this makes our source xml not compatible with docbook (am
I wrong here ?) 

> 
> > 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. 
> 
> No thoughts on this at the moment, but it sounds hard, I'm not
> completely sure I see the advantage, either. Your documents tend to
> contain a lot of Dia-generated diagrams. Other documents contain
> marked-up screenshots that are created from a few layers in the Gimp, in
> other case, SVG images might be a good idea. It looks like a slippery
> road here; where do we stop with "special format" display modes?
I can live with svgs or, at worst, pngs. I was just dreaming :) 

[snip] 

> Mathieu, if you are going to put in the effort to write good developer
> documentation, then it would be nice if we can support you with the
> technology to make a good user experience. To date, this sort of stuff
> has not been high priorty. Maybe it's time to change that. In my own
Even if I don't end up writing all the things I am thinking about, if we
can write a small db document which describes how all this works, it
will be useful for the developers who can write themselves the docs and
can refer to something which tells them how to do it. 

[snip] 

> Like I said above, I want to think about this a bit more and maybe work
> out how we get from "here, today" to "over there, where it's perfect and
> easy" in twelve really hard steps.
That would be great :) 

As a side note, I wonder how Sun solves this problem. Or if they solve
the problem at all. 

Finally, since I have started dreaming openly, I'd like to point out
that the coolest thing we could do ever would be to have our own xsl:fo
xslt for xml docbook to render our source xml to pdf or ps with working
cross-refs in the resulting document. But, yeah, this is really a dream.

Mathieu 

-- 
Mathieu Lacage <mathieu_lacage realmagic fr>
#p: +33 1 69 19 61 97