Menu
▾
▴
scrollkeeper-devel
|
From: Bob S. <bo...@sc...> - 2000-11-29 18:42:14
|
[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?
Thanks for taking the time to help me understand this.
bobs
Bob Stayton 400 Encinal Street
Publications Architect Santa Cruz, CA 95060
Technical Publications voice: (831) 427-7796
The Santa Cruz Operation, Inc. fax: (831) 429-1887
email: bo...@sc...
|
|
From: Ali A. <ali...@au...> - 2000-11-29 20:55:55
|
* 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
|
|
From: David M. <dme...@lu...> - 2000-11-30 00:36:30
|
On Wed, Nov 29, 2000 at 09:59:55PM -0200, Ali Abdin wrote: > 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). You just contradicted yourself and confused me. If the XML is a purely internal data structure, why is Nautilus reading it? -- Dr. David C. Merrill http://www.lupercalia.net Linux Documentation Project dme...@lu... Collection Editor & Coordinator http://www.linuxdoc.org Boucher's Observation: He who blows his own horn always plays the music several octaves higher than originally written. |
|
From: Laszlo K. <las...@su...> - 2000-11-30 10:08:43
|
> On Wed, Nov 29, 2000 at 09:59:55PM -0200, Ali Abdin wrote: > > 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). > > You just contradicted yourself and confused me. If the XML is a purely > internal data structure, why is Nautilus reading it? The way how it works is that XML files are exported from Scrollkeeper to the browser. The main Content List (where every entry is a different doc), the TOCs of each doc and the combination of the two (called the Extended Content List) are all XML files. Apart from that everything Ali wrote is valid (about the availability of the XML parsers on various platforms, Gnome, Nautilus etc). Laszlo |
|
From: Laszlo K. <las...@su...> - 2000-11-30 11:25:21
|
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
|
|
From: Dan M. <d-...@uc...> - 2000-12-01 17:16:38
|
On Thu, 30 Nov 2000, Laszlo Kovacs wrote: > Bob Stayton wrote: > > 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. Right now we are focussing on the internal workings of ScrollKeeper and how documents are installed. Note that eventually only scrollkeeper itself will care how it sorts and stores its data. We can always change to another method to store the internal data if we find a better way. Once we have things working better and the design has stabalized, we can start putting in a real library to export to help browsers. For right now, ScrollKeeper actually points the help browser to its ScrollKeeper's internal database files which are in XML format. This is enough to get it working with GNOME's help browser and any others which are willing to handle XML files. We can use this for testing and development. (Remember, we don't even have a 0.1 version done yet.) As things mature, we will eventually hide the internal database from the help browser and provide a real exported API which potentially will support not only XML-aware help browsers but perhaps others as well (if there is a demand for it). As for just supporting GNOME and KDE, this is definitely *not* the intention. There are many people who do not use GNOME or KDE, and that will always be the case. I would be happy to see another help browser which is independent of these two desktops and which can utilize scrollkeeper. If there was a compelling reason to use some format other than XML, then scrollkeeper's API could be extended. Dan |
|
From: Greg F. <gf...@ho...> - 2000-11-30 15:04:33
|
On Nov 30, 10:08am, Laszlo Kovacs wrote: > Subject: Re: [Scrollkeeper-devel] questions, questions > > On Wed, Nov 29, 2000 at 09:59:55PM -0200, Ali Abdin wrote: > > ... > > You just contradicted yourself and confused me. If the XML is a purely > > internal data structure, why is Nautilus reading it? > > The way how it works is that XML files are exported from Scrollkeeper > to the browser. The main Content List (where every entry is a different > doc), the TOCs of each doc and the combination of the two (called the > Extended Content List) are all XML files. Apart from that everything Ali > wrote is valid (about the availability of the XML parsers on various > platforms, Gnome, Nautilus etc). Does the browser receive a ptr to the contents of the file, ptr to the filename, ptr to an internal XML-based data struct, or something else? Or put a different way - is there a spec available for the public API? thx. -- Greg Ferguson - s/w engr / mtlhd | gferg at sgi.com SGI Tech Pubs - http://techpubs.sgi.com/ | Linux Doc Project - http://www.linuxdoc.org/ | gferg at metalab.unc.edu |
|
From: Ali A. <ali...@au...> - 2000-11-30 22:46:56
|
* David Merrill (dme...@lu...) wrote at 18:09 on 30/11/00: > On Wed, Nov 29, 2000 at 09:59:55PM -0200, Ali Abdin wrote: > > 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). > > You just contradicted yourself and confused me. If the XML is a purely > internal data structure, why is Nautilus reading it? Yes, I did contradict myself :) Its not really an internal data structure or file format. It is an external one, and instead of devising our own, we used an easily parsable existing one...XML. I mean if you really want we could use a fast binary database, but I doubt people would appreciate that ;) The real reason though is: To be buzzword compliant :) Regards, Ali |
|
From: Ali A. <ali...@au...> - 2000-12-01 07:03:24
|
* Greg Ferguson (gf...@ho...) wrote at 02:57 on 01/12/00: > On Nov 30, 10:08am, Laszlo Kovacs wrote: > > Subject: Re: [Scrollkeeper-devel] questions, questions > > > On Wed, Nov 29, 2000 at 09:59:55PM -0200, Ali Abdin wrote: > > > ... > > > You just contradicted yourself and confused me. If the XML is a purely > > > internal data structure, why is Nautilus reading it? > > > > The way how it works is that XML files are exported from Scrollkeeper > > to the browser. The main Content List (where every entry is a different > > doc), the TOCs of each doc and the combination of the two (called the > > Extended Content List) are all XML files. Apart from that everything Ali > > wrote is valid (about the availability of the XML parsers on various > > platforms, Gnome, Nautilus etc). > > Does the browser receive a ptr to the contents of the file, > ptr to the filename, ptr to an internal XML-based data struct, > or something else? > > Or put a different way - is there a spec available for the public API? Right now there is no library at all. You have to manually locate and parse the file ;) The project is still at 0.0.1 for a reason. Perhaps when there is a library we can have functions to get the ptr to the filename and a function to return the "internal XML-based data struct" (a.k.a xmlDocPtr) You could perhaps also recieve document "fragments" (xmlNodePtr?) Regards, Ali |