Re: docbook crossrefs

[Malcolm Tredinnick <malcolm commsecure com au>]

On Tue, Dec 10, 2002 at 07:12:01PM +0100, Mathieu Lacage wrote:
> 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 ?) 

Not really. One approach is olink tags for the external links. Docbook
specifies that the way these are processed are application independent
and Norm Walsh's Docbook stylesheets includes a number of parameters you
can set to control this processing. Further, later versions of these
stylesheets (somewhere around 1.55 or maybe one or two versions earlier)
changed this a bit further so that things are now really smooth.
However, GNOME 2.0 standardised on the 1.48 version of the stylesheets.
We should maybe look at changing this for GNOME 2.2, but it requires a
fair bit of testing to do this and we may just not have time.

Have a look at chapter 12 of this document for an idea of what I am
talking about here.

	http://www.sagehill.net/xml/docbookxsl/

(I have been using this approach for some large document collections at
work and it works out fairly nicely.)

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

Agreed. Keep notes as you go and let's pool them together at some point
(I have some; others probably do, too).

Cheers,
Malcolm

-- 
Plan to be spontaneous - tomorrow.