Re: [Scrollkeeper-devel] Index support

[Laszlo K. <las...@su...>]

John Fleck wrote:
> 
> Hi,
> 
> I've mocked up a short DocBook document below with what I hope are
> relatively complete examples of the use of indexterm tags as an
> example to get our discussion of indexing in ScrollKeeper started.
> 
> From a functional point of view, I'd like the system to be capable of
> two things:
> 
> 1) Providing the data necessary to the help system browser to generate a
> system-wide index of all the documents registered with ScrollKeeper
> 
> 2) Providing the data necessary for the browser to generate a
> document-specific appendix for a particular document

Could you detail the appendix a bit please? I am not sure what it is
exactly. Apart from this I think Scrollkeeper should be able to extract
index from one doc and offer that two the user. We can build a
system-wide index on that as offered by Scrollkeeper or we can leave it
to the browser to do this.
 
> An optional third capability I'd like to consider is a middle ground
> that is likely implicit in 1) above, the capability to generate a
`> system-wide index for all the documentation in a given SK category.
This is simple if we store separately the index info of each doc.

> This seems reasonable. I see something along these lines, with a
> series of "terms" - the terms to be listed in the index - with an
> "instance" for each occurence of the term as an indexentry in a
> document. Each instance would then record the necessary anchor
> information. To be most useful, we should record both the id of
> the indexterm itself and the id of the enclosing sect. That would
> allow flexibility for the help browser folks.
Storing the enclosing sect also might be a good idea.

> 
> I leave the specifics of the xml data structure to the wizards in the
> group, but conceptually I'm thinking of something along these lines:
> 
> ***************************************
> 
> <indexentry term="term"> (this would be based on the primary term in
>                           an indexterm)
> 
>         <instance>
>                 <secondary>secondaryterm</secondary> (optional)
> 
>                 <doc>/pathtofile/filename.sgml</doc> (the location of
>                                                       the file)
> 
>                 <category>category</category>        (the omf category
>                                                       of the doc)
> 
>                 <sectid>sectid</sectid>              (the id of the
>                                                       section in which
>                                                       the indexterm is
>                                                       located)
> 
>                 <indextermid>idid</indextermid>      (the id of the
>                                                       indexterm
>                                                       itself)
> 
>                 <indextermrangeend>anotherid</indextermrangeend> (the
>                                                       id for the end
>                                                       of the indexterm
>                                                       range if used)
> 
>                 <seealso>otherterm</seealso>         (a pointer to
>                                                       another term - optional)
>         </instance>
> 
>         <instance>
>             ............. another instance .............
>             ............. possibly in the same doc .....
>             ............. or a different one ...........
>         </instance>
> 
> </indexentry>

This sounds resonable with the addition that we are looking into the
implementation of a doc id that would be the same for a doc and all its
translations, so the actual information about the doc stored here might
be a bit different.

> 
> *****************************************
> 
> Some questions to consider:
> 
> - how should we handle locale? I expect we should have a separate xml
> index file for each locale, based on the language code in the omf.
Yes. This should be pretty similar to the TOC implementation. Right now
Scrollkeeper assigns a unique id to every installed doc and the TOC of
the doc is stored in the TOC subdirectory of the scrollkeeper database
directory in a file that has the ID as its name.
 
> - DocBook indexterm also supports attributes "zone," "significance",
> "scope" and "pagenum". How should we treat those?
I have no idea, this is up to people who know more about SGML in
general.

Finally dont be shy to cut out everything from your mails quoted texts
that is not related as we already managed to grow emails to unbearable
sizes at previous design related discussions.

Laszlo