Re: XML DocBook patch

[Owen Taylor <otaylor redhat com>]

Matthias Clasen <maclas gmx de> writes:

> Am Son, 2002-04-28 um 23.32 schrieb Damon Chaplin:
> > On Sun, 2002-04-14 at 04:16, Matthias Clasen wrote:
> > > > Any ideas about the cross-references?
> > > > Maybe we can use a <ulink> element with a special URL type that the help
> > > > viewer understands and knows how to resolve.
> > > 
> > > The docbook means for inter-document links is olink. 
> > > 
> > > http://docbook.sourceforge.net/projects/dsssl/doc/olinksemantics.html
> > > 
> > > If the help viewer claims to support docbook, it should understand olinks.
> > 
> > Though it looks a bit awkward as you have to use entities with PUBLIC or
> > SYSTEM identifiers to point to the target document.
> > 
> 
> No, this would be the SGML-way which is of course no longer acceptible
> in the new world order where every acronym must start with X. I know
> people are working on making olink work with xpointers and there is
> XSL out there for this (I don't have the links handy, you may be able to
> find it somewhere on www.docbook.org, I can provide links tomorrow)
 
It should be noted that we don't have a target document here, we
just know there is some function called pango_layout_new() we want 
to link to.

So, we can't expect any pre-existing support to really do what
we want, what we instead need to do is represent the link in
some unambiguous way in the docbook, probably via olink.

Then our tools, whether gtkdoc-db2html + XSL stylesheets, or 
a convert-on-the-fly approach have to worry about:

 - Maintaining an index of all functions.
 - Mapping links either statically or at run time.

There is certainly going to have to be application specific handling
here, and that is anticipated in the design of olink, though 
I wish they hadn't anticipated quite _so_ much generality
in olink.

> > Also, I don't know if yelp would handle this.
> 
> Of course, native docbook support has more to worry about than
> cross-document links. First of all, we will have to switch from an 
> everything-is-a-programlisting approach of markup to a more semantic
> markup using funcsynopsis and descendents.

Why?

Regards,
                                        Owen