Re: [Scrollkeeper-devel] Index support

[John F. <jf...@sw...>]

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

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.

On Tue, Mar 13, 2001 at 05:21:05PM +0000, Laszlo Kovacs wrote:
>
> Anyway I think the way it should be done is that we take the SGML file
> and extract the index info from it into a very simple xml file. Ideally
> this should contain only the index strings and the "anchor" in the text
> that is associated with them.

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.

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> 

*****************************************

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.

- DocBook indexterm also supports attributes "zone," "significance",
"scope" and "pagenum". How should we treat those?

A sample doc:
***********************************************************
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
]>
<article id="index">

  <sect1 id="sect1-01">
    <title>Indexterm</title>
    <para>
      <indexterm id="idx-id1">
	<primary>indexterm</primary>
      </indexterm>
      This paragraph contains some content that will be indexed using an
      ordinary single-point indexterm.</para>
  </sect1>

  <sect1 id="sect1-02">
    <title>Range</title>
    <para>
      <indexterm id="idx-id2" class="startofrange">
	<primary>indexterm</primary>
	<secondary>range</secondary>
      </indexterm>
      This paragraph contains some content that will be indexed using an
      indexterm range.
      <indexterm startref="idx-id2" class="endofrange">
	
    </para>
  </sect1>


  <sect1 id="sect1-03">
    <title>Seealso</title>
    <para>
      <indexterm id="idx-id3">
	<primary>seealso</primary>
	<seealso>indexterm</seealso>
      </indexterm>
      This paragraph contains content regarding the seealso tag, with a seealso
      reference to indexterm in the index.
    </para>

    <sect2 id="sect2-01">
      <title>Indexterm in nested sect2</title>
      <para>
      <indexterm id="idx-id4">
	<primary>nested</primary>
      </indexterm>
	Here is some text in a sect2 that will be indexed.
      </para>
    </sect2>

  </sect1>

</article>
*****************************************************

Cheers,
-- 
John Fleck
jf...@sw... (h)
jf...@ab... (w)
http://www.abqjournal.com/scitech/