Re: [Scrollkeeper-devel] Scrollkeeper file format improvements?

[Dan M. <d-...@uc...>]

On Tue, 26 Jun 2001, L=E1szl=F3 Kov=E1cs wrote:

> First the index, the Scrollkeeper format is this:
>
>   <primary>
>     <title>Front</title>
>     <secondary>
>       <title>Panel</title>
>       <tertiary>
>         <title>applets</title>
>         <see indexid=3D"id2597162">Panel, Testing, Zone</see>
>       </tertiary>
>     </secondary>
>   </primary>
>
> The JavaHelp format is like this:
>
> <indexitem text=3D"adding an existing portfolio" target=3D"proj.import"=
 />
> <indexitem text=3D"adding an existing project">
>     <indexitem text=3D"naming the project" target=3D"proj.importdirecto=
ry"
> />
> </indexitem>
> <indexitem text=3D"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.

So we would have:
   <indexitem>
     <title>Front</title>
     <indexitem>
       <title>Panel</title>
       <indexitem>
         <title>applets</title>
         <see indexid=3D"id2597162">Panel, Testing, Zone</see>
       </indexitem>
     </indexitem>
   </indexitem>

Right?

I think either way is fine.

> 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=3D"intro">Introduction
>     <tocsect2 linkid=3D"whatisscrollkeeper">What is ScrollKeeper?
>     </tocsect2>
>     <tocsect2 linkid=3D"aboutthisdoc">About This Document
>     </tocsect2>
>     <tocsect2 linkid=3D"authors">Authors
>     </tocsect2>
>     <tocsect2 linkid=3D"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.

Sounds reasonable.  I think the reason they are there are because DocBook
uses <sect1>, <sect2>, etc.  It would be interesting to know the reason
why DocBook numbers their sections.  I suspect it is (a) for the author,
since they read and write the markup and having numbers helps keep them
from getting confused, and (b) <books>, <articles>, etc. have strict rule=
s
on how they can be sectioned.  Neither of these really apply here, so I
think we can do away with the numbers if there is any incentive to do so,
such as making things simpler.

> The JavaHelp TOC file is:
>
> <tocitem image=3D"toplevelfolder" text=3D"Java Development Environment"=
>
>     <tocitem target=3D"jde.intro">Introduction to JDE Online Help />
>     <tocitem text=3D"IDE Tutorial" target=3D"tut.starttoc">
>         <tocitem text=3D"Introducing JDE" target=3D"tut.intro" />
>         <tocitem text=3D"Tutorial One" target=3D"tut.quickstart" / >
>         <tocitem text=3D"Tutorial Two" target=3D"tut.edit" />
>         <tocitem text=3D"Tutorial Three" target=3D"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.

Somebody mentioned on this list a little while back that one should not
have "running text" as an attribute.

Dan