Re: omf, xml

[Damon Chaplin <damon ximian com>]

On Wed, 2002-05-08 at 09:51, John Fleck wrote:
> Folks -
> 
> Two issues came up at a release GNOME2 release team meeting involving
> API documentation. Neither is GNOME-specific. Both would allow docs
> produced by gtk-doc to be more easily integrated.
> 
> 1) Is it possible to register API docs with ScrollKeeper? This seems
> like a good idea, as it will allow any SK-aware help browser (both
> GNOME's and KDE's are) to know the docs' location. It's relatively
> straightforward - we simply need to create and install an OMF file.

Currently we usually only install html for API docs.
I don't know if scrollkeeper handles html docs or if it is worth
trying to do this as we want to move to DocBook XML at some point.

 
> 2) DocBook xml. This is harder, but in conjunction with SK, API docs
> written in DocBook xml could be indexed and therefore more easily
> searchable. Because DocBook xml uses the libxml/libxslt toolkit, this
> also would avoid the regular problem of jade/docbook installation that
> so many first-time cvs builders confront. (Both GNOME and KDE are
> switching to DocBook xml for their user manuals.)
> 
> Neither of these things should be done now, but I wanted to get a
> discussion started, to see how this fits into gtk-doc's future plans.

We want to switch to DocBook XML. The main issue to resolve is
cross-references between documents. Currently we fix the html links with
a perl script, but we need a different method for DocBook XML.
Something like custom XSLT code to handle our own <olink> elements.

Also, people seem to still want HTML output available, so we need a
solution that generates DocBook XML and HTML, all with cross-references
fixed up.


One thing we could do is just drop cross-references between documents
for now, and fix it later. But that means people may have to update
their docs & Makefiles twice.

Damon