Re: omf, xml

[Dan Mueth <muet alumni uchicago edu>]

On 8 May 2002, Mikael Hallendal wrote:

> ons 2002-05-08 klockan 21.00 skrev Damon Chaplin:
> > On Wed, 2002-05-08 at 09:51, John Fleck wrote:
> > > Folks -
> 
> Hi!
> 
> > > 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.
> 
> I think scrollkeeper handles html (as long as you provide an omf file
> for it). 

ScrollKeeper won't be able to extract the index or the table of contents 
from HTML docs, but it could at least keep track of the document title, 
language, location, and subject so that it can appear in the contents list 
of all documents and be easy for users to find.  So, I think it is still 
worthwhile even for HTML docs.

As for cross-referencing with XML documents... In the past we handled this
for user documentation by employing the "gnome-help" URI scheme, which the
GNOME help browser would translate into an absolute path.  It requires
that all GNOME apps install their documentation in a certain path (aside
from the $prefix), but gets the job done.  

Eventually we will probably build the URI resolution into ScrollKeeper so
that instead of looking where we think the document should be installed,
we can just query where the document was installed.  This makes things
easier for cross-desktop help browsers, who probably don't want to keep
track of the conventions of where each project installs its docs for each 
application and locale.

Dan