Re: [Scrollkeeper-devel] question re: marking index terms

[Laszlo Kovacs <laszlo kovacs sun com>]

> XSLT is XML StyleSheets Language Translations (or something very much
> like that).  It's a programming language designed specificly for
> transforming XML into another form of XML or another formatted document.
> It will be used to replace gnome-db2html2, and probably the db2* scripts
> for GNOME authors as we move our docs to being truly XML compliant.
Will still convert to HTML?

> As for how this affects Scrollkeeper's index extraction...  Well, this
> depends on a few things which I don't understand yet, so allow me to
> think outloud for a minute.  First, we need to agree upon some markup
> conventions for our docs.  I don't have enough of an understanding of
> indexing, yet, to be able to recomend anything here.  Once we have some
> docs with real index terms in them, we need to figure out what we do
> with those.  There are two options that I can see.  First, we can ship
> just the XML docs, and rely on the help browser and/or scrollkeeper to
> generate the index from the docs, and present that index to the user.
> Second, we could use a script similar to Norm Walsh's 'collate-index.pl'
> to extract the index into an 'document-index.xml' file, and ship both
> the doc, and that extracted index.  Of these two, the former makes the
> most sense to me.
Yeah, I heard about this script. I dont know what it does exactly
though. Apart from having index associated with every doc we will
probably want to search through merged indexes of several docs (grouped
through various criteria). Although it is not clear how much of this is
Scrollkeeper's job and how much is the browser's.

> What I'm really having a problem understanding is how we make the help
> browser and scrollkeeper talk together for this index.  Looking at the
> first markup that Mary gave an example of, there is no "id" tag for
> these index terms.  Without an id tag, I'm not sure how the help browser
> would know which occurance of the indexterm to link to.  I think that
> this will pose some problems for linking to index terms.  This leaves us
> with needing to use markup as shown in the second example.  Please
> comment on this conclusion, as I've just come up with it.
This is how I see the situation. But it really depends on what kind of
content display component we have. I dont know enough about this side,
but I cant imagine it to work without index IDs.

> Back to how this affects scrollkeeper and gnome-db2html2...
> gnome-db2html2 probably doesn't support this markup very well, although
> it shouldn't cause it to crash (I believe).  So even if scrollkeeper was
> capable of generating an index based on this, the gnome help system
> would be unable to utilize said index for the moment.  Moving to XSLT
> and support for the complete set of elements and attributes provided in
> DocBook is my preferred solution for this, although others may argue to
> extend gnome-db2html2 to support this.
> Most of what I've said here is GNOME specific, rather than scrollkeeper
> general, which may be a problem.  Other projects may decide to use
> different markup for indexing, or may make other decisions which add to
> life's little challenges.  Does anyone know of a way in which
> scrollkeeper could easily utilize both forms of markup for indexing?
> Enough from me for the moment, ttyl,

As far as I understand we dont really know how the content display will
work in Gnome 1.4.1 and Gnome 2.0. This should probably be clarified
before we pick any approach with Scrollkeeper as the Gnome Help Browser
is the main (and only) client of Scrollkeeper right now.

Laszlo