Re: [Scrollkeeper-devel] questions, questions

[Laszlo K. <las...@su...>]

Bob Stayton wrote:
> 
> [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?

yes.

> 
> Also, this database does not actually contain the OMF data
> itself, right?

yes.

> 
> 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.

yes, but I would probably add the Content List files for each locale
also.

> 
> 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

yes.

> 
> 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.

yes.

> 
> 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?

yes. However we do not use this at all at the moment.

> 
> 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.

Yes, but this is actually implemented according to proposal #3. You can
find how the TOC and the extended content list looks like at the end of
the proposal, I think.

> 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.
Yes this is correct. I think what the above meant is that when you
install a doc with Scrollkeeper, a TOC is generated for it, when you
uninstall it, this is deleted. So there will not be TOCs hanging around
that don't have their doc installed with Scrollkeeper.

> 
> 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?
I think I answered this above. The TOC is XML file, generated from the
doc and offered to the browser. So you have a content list (one entry
for each doc) and each doc from this has a TOC. This is all offered to
the browser. Also The content list file and the TOCs combined form the
so called extended content list. We are not sure how useful it is to
have an extended content list, we will see this later.


> 
> 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?
I think Ali answered this mostly. Any browser can use Scrollkeeper as
long as they understand XML.

Laszlo