Re: [Scrollkeeper-devel] structure of extracted index page

[Dan M. <da...@ea...>]

[removing gnome-doc-list from cc list since this email is getting into the
internal guts of SK]

On Wed, 25 Apr 2001, Mary Dwyer wrote:

> Example:
> 
> <indexdoc>
>    <indexentry linkid="idx-a1">Apple, Big, Green
>    </indexentry>
>    <indexentry linkid="idx-a2">Banana, Small
>    </indexentry>
>    <indexentry linkid="a1">Orange, Medium
>    </indexentry
>       
>    etc. .......
>    
> </indexdoc>   

There is nesting information which is left out.  For example, if you also
have "Apple, Big, Blue", the markup above does not reveal that your index
looks like:
  Apple
      Big
          Green  *
          Blue   *
  Banana
      Small      *
  Orange
      Medium     *

I think it makes sense to put this into the XML file, since this is the
way the data will typically be displayed and processed.  If SK does the
work of sorting this out then things will be faster and easier for the
help browsers.

Note that for <see> and <seealso>, they are actually creating links
*within* the index, pointing to other parts of the index.  For these we
can either describe their position by creating an id for them or by
specifying the full index term they link to.  I'm not sure which is
better, but introducing id's seems reasonable.

For example, one might use:

<indexdoc>
  <primary>
     <title>Apple</title>
     <secondary>
       <title>Big</title>
       <tertiary>
          <title linkid="idx-a1">Green</title>
          <title linkid="idx-a3">Blue</title>
          <seealso seeid="sa-1">New York City</seealso>
       </tertiary>
     </secondary>
   </primary>
   <primary>
     <title>Banana</title>
     <secondary>
       <title linkid="idx-a2">Small</title>
     </secondary>
   </primary>
   <primary>
     <title id="sa-1" linkid="idx-a5">New York City</title>
   </primary>
</indexdoc>

or

<indexdoc>
  <primary title="Apple">
    <secondary title="Big">
      <tertiary title="Green" linkid="idx-a1"/>
      <tertiary title="Blue" linkid="idx-a3"/>
      <seealso title="New York City" seeid="sa-1"/>
    </secondary>
  </primary>
  <primary title="Banana">
    <secondary title="Small" linkid="idx-a2"/>
  </primary>
  <primary title="New York City" id="sa-1" linkid="idx-a5">
  </primary>
</indexdoc>

So, here SK generated the id "sa-1" which is used to link to "New York
City" in the index, while "idx-a5" is the id assigned to the index term by
the author for linking from the index into the body of the document.

Does this seem reasonable?

Dan