[Scrollkeeper-devel] Scrollkeeper file format improvements?

[<las...@Su...>]

Hi,

Scrollkeeper recently went through a review here in Sun (everything
deployed with the Gnome desktop has to). The reviewers advised me to
look at JavaHelp that tries to achieve similar goals (including a
browser provided) as Scrollkeeper. I looked primarily to the metadata
files of the docs and their might be some improvements we could make to
the Scrollkeeper files based on that. Another angle is that 

I've been advised to write a paper about conversion possibilities of
Scrollkeeper files to JavaHelp format in case we would ever like to add
JavaHelp support to Scrollkeeper. Considering this changes that don't
improve, but don't limit either could make my work easier.

Considering all these I can see improvements being made to our TOC and
index format.

First the index, the Scrollkeeper format is this:

  <primary>
    <title>Front</title>
    <secondary>
      <title>Panel</title>
      <tertiary>
        <title>applets</title>
        <see indexid="id2597162">Panel, Testing, Zone</see>
      </tertiary>
    </secondary>
  </primary>

The JavaHelp format is like this:

<indexitem text="adding an existing portfolio" target="proj.import" /> 
<indexitem text="adding an existing project"> 
    <indexitem text="naming the project" target="proj.importdirectory"
/> 
</indexitem> 
<indexitem text="analyzing program performance, see  profiler " />

I think replacing our primary, secondary, tertiary tags with indexitem
would be a good move. This would allow infinite amount of index levels,
the processing of the file would be easier in the help browser and the
DTD would be simpler (I think, I am not a DTD expert). The rest should
stay as their are technical reasons for them to be as they are.

Second the TOC:

Functionally JavaHelp and Scrollkeeper files are the same so there is
only a little room for changes with obvious benefit. 

Scrollkeeper format is:

<tocsect1 linkid="intro">Introduction
    <tocsect2 linkid="whatisscrollkeeper">What is ScrollKeeper?
    </tocsect2>
    <tocsect2 linkid="aboutthisdoc">About This Document
    </tocsect2>
    <tocsect2 linkid="authors">Authors
    </tocsect2>
    <tocsect2 linkid="scrollkeeperlicense">ScrollKeeper License
    </tocsect2>
</tocsect1>

The numbering of the tocsects caused me tremendous problems while
writing the TOC extractor stylesheet (although that was my first ever
stylesheet, it is not that difficult actually). I think we should get
rid of those numbers regardless of other changes. The only help browser
using Scrollkeeper currently that I know of is Nautilus and it doesn't
use those numbers at all. No code change would be needed there if the
numbers go.

The JavaHelp TOC file is:

<tocitem image="toplevelfolder" text="Java Development Environment"> 
    <tocitem target="jde.intro">Introduction to JDE Online Help /> 
    <tocitem text="IDE Tutorial" target="tut.starttoc"> 
        <tocitem text="Introducing JDE" target="tut.intro" /> 
        <tocitem text="Tutorial One" target="tut.quickstart" / > 
        <tocitem text="Tutorial Two" target="tut.edit" /> 
        <tocitem text="Tutorial Three" target="tut.errors" /> 
    </tocitem>  
</tocitem>

It holds the same info as Scrollkeeper's, if there is no technical
reason against it, I would support switching to it.

Thoughts?

Laszlo