Re: [Scrollkeeper-devel] questions, questions

[Ali A. <ali...@au...>]

* Bob Stayton (bo...@sc...) wrote at 21:52 on 29/11/00:
> [Pardon me if you receive a duplicate of this message.
> The first copy didn't seem to make it to the list.]
> 
> I've been studying the current design (proposal #3) of
> scrollkeeper and catching up on the recent sk mail.  Thanks
> for sorting out the issues into smaller mails.
> I would like to present scrollkeeper to some colleagues, but
> there are some areas that I need to ask you questions about.
> I'll try to keep this short. :)
> 
> I'm a little confused about the database, the Contents List,
> and TOCs.  From the design document, it appears that the
> database is a flat file database named scrollkeeper-docs
> that consists of records with four fields:
> 
> <URI to OMF file>  <uniqueID>  <URI to document>   <timestamp>
> 
> This file has one record for each document registered
> with sk, right?
> 
> Also, this database does not actually contain the OMF data
> itself, right?
> 
> So the "master" source for each document's OMF
> data resides in its OMF file.  In effect, the database
> of OMF data is a combination of the scrollkeeper-docs
> file and the collection of OMF files its records point to.
> 
> A Contents List is a selection of data from this extended
> database that is serialized into an XML file.  Each Contents
> List contains information on documents in one language,
> since the function "scrollkeeper-get-contents-list <language>"
> returns the path:
> ${pkglocalstatedir>/<language>/scrollkeeper-contents-list.xml
> 
> Within a Contents List file, the documents are sorted into
> the category hierarchy within nested <sect> elements. 
> Each document's data is listed within a <doc> element.
> An alternative proposal from Nik has the documents in a
> flat list with the categories as subelements for each
> document to reduce data redundancy.
> 
> The data in a <doc> element is a selection of the
> OMF data for the document, right?  In the example,
> I saw title, source, format, and <docomf>.  I presume
> the <docomf> is there so an application can track down
> the OMF file if they need more of its data? 
> 
> Proposal #3 also mentions that for each SGML and XML document,
> a document TOC is extracted and kept in the TOC directory
> under an IDNUMBER.  This is to be inserted into the
> extended Contents List.  Its format is to be determined.
> 
> But then some later mails described generating a ToC from
> a Contents List: 
> 
>   Date: Wed, 22 Nov 2000 21:55:45 -0600 (CST)
>   From: Dan Mueth <d-...@uc...>
> 
>   > It's my understanding that there's a 1:1 mapping between a Contents List
>   > and a ToC.  That is, you can't have a ToC that includes information
>   > about documents that aren't in the Contents List.
> 
>   Yes.
> 
> This was one of those long mails (8^) and I kind of lost track
> of the context, so I wasn't sure what it was talking about.
> It is my understanding that the help browser was supposed
> to read the Contents List and present that to the user.
> What ToC has a 1:1 mapping to the Contents List?  Is that
> an HTML file generated from the Contents List?
> 
> Also, there seems to be a running assumption that an
> XML-aware browser is available that understands a
> Contents List and can present it to the user.
> Is this based on the Gnome and KDE browsers under development?
> Are other applications expected to use the Contents Lists?

XML is just the file format that ScrollKeeper uses to store its own "data".
Wether GNOME and KDE have an XML browser is irrelevant. The fact is,
ScrollKeeper could have used its own non-standard file format, or it could
have used the easily parsable XML file format (there are tons of XML parses on
almost all platforms, and it beats creatign your own parser for the format).
ScrollKeeper uses libxml to do its own parsing, so that does limit your
choices (but libxml is cross-platform, doesn't depend on any other libraries
(although it is part of the GNOME platform), and it is written in C (meaning
you can create wrapper APIs in other languages)).

GNOME has a file-manager called Nautilus (in development), in this file
manager there is a 'Help Sidebar'. This sidebar presents the documents
installed on the system to the user. Sun submitted a patch to make it utilize
the scrollkeeper XML file.

When you select an item in this Help Sidebar, /then/ the Help Browser starts
up and displays the document (based on the document URI).

Regards,
Ali