scrollkeeper-devel — Developer discussion list for ScrollKeeper

Re: [Scrollkeeper-devel] What about the distributions?

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

On Thu, 19 Oct 2000, Eric Bischoff wrote:

> > 4) Did you literally mean to use the name "doc-contents.omf"?  This makes
> > me think of the contents list which isn't really what this file is.
> 
> Well, I don't really see why the contents list should reside in a
> different database. But this is another topic and maybe it's already
> been discussed.

The idea is that each time a doc and its metadata gets installed, we want
the system to automatically update several files.  One is the contents
list - a subject-sorted tree of documents on the system.  Another is the
table of contents(TOC) for the doc.  Another is what I'm calling an
"extended contents list".  This is the contents list with the TOC merged
into it so one could potentially navigate not only through the list of
docs on your computer, but down into particular sections of a doc.  There
may be more things in the future.

Since these files generally contain information about many documents and
are XML documents where position in the documen matter, we cannot simply
concatenate each new doc to the bottom.

(Sorry if I am misunderstanding you and you already know all this.)

After chatting with Jonathan for a while, he convinced me we should use
variables which get passed to the script.

Hopefully I haven't mutilated his idea.  I think we would do it like this:

pre-install makes a file, say '<packagename>-docs.omf'.  This is created
by merging the various OMF metadata files in the package, replacing the
URI's for each doc with the actual location it will be installed.

install does two things:

First, it installs <packagename>-docs.omf
Second, it does: scrollkeeper-install -p <path> <packagename>-docs.omf

Here <path> is the path to the scrollkeeper directory in /var, or perhaps
a particular file in this directory.

The <path> can be set by the Makefile.am:
	$(localstatedir)/mydatabase

Autoconf turns $(localstatedir) into $(prefix)/var/ which RPM likes.  So
if we are doing a plain 'make install', it points to the right place.  If
we are doing an RPM 'make install', it points into $BUILDROOT/var.

I suppose we could use this as a conditional test for whether scrollkeeper
actually enters the info into its own files.  Alternately, we could
actually have scrollkeeper run, placing the generated info under
$BUILDROOT which will be deleted later.

Does this seem reasonable?
 
Dan

Re: [Scrollkeeper-devel] Re: Scrollkeeper code checked in

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

On Wed, 18 Oct 2000, Ali Abdin wrote:

> * laszlo kovacs (las...@su...) wrote at 00:02 on 17/10/00:
> > Hi,
> > 
> > I checked in most of the implementation of the proposal from:
> 
> This is excellent news! :) I need to check out the code sometime soon. I was
> just curious, but perhaps this should be announced to various Documentation
> projects (just in case people want to throw in their comments and/or want to
> contribute). Of course this should only be done when the code is in a "state"
> to accept contributions.

We definitely should do this, but I think we should wait until we have at
least a complete pre-release of 0.1.  Hopefully we can resolve the
remaining issues quickly.

> > The Scrollkeeper files go into prefix/var/lib/scrollkeeper.
> 
> Umm - which scrollkeeper files are you talking about? Are these the OMF files?
> Shouldn't they go into prefix/share/scrollkeeper?

This is something we should discuss on this list.  ScrollKeeper generates
and updates a number of files which store things like the contents list
describing all docs on the system.  Where does this file belong?  My
original proposal had everything under something like
prefix/share/scrollkeeper.  However, I don't think we can put files which
scrollkeeper edits under here can we?  Apparently /usr must be mountable
read-only.  I don't know if /share has the same requirements, but I'm
guessing it does.  My understanding is that we should use /var for these
files which scrollkeeper frequently modifies.

The original OMF files which the packages install (as well as the docs
themselves) are only read by ScrollKeeper, not moved or edited.

Dan

[Scrollkeeper-devel] Re: Scrollkeeper code checked in

[laszlo k. <las...@su...>]

> This is excellent news! :) I need to check out the code sometime soon. I was
> just curious, but perhaps this should be announced to various Documentation
> projects (just in case people want to throw in their comments and/or want to
> contribute). Of course this should only be done when the code is in a "state"
> to accept contributions.
The biggest problem is probably that is not that easy to test it as
there is not much documentation out there with the related OMF files.
Maybe we should generate some and put them on the project web page?
There is a quite large number of OMF files in the OMF repository (link
from the project web site). Otherwise the code is ready to be tried.

> Umm - the OMF file is an XML file, correct? libxml should handle validation I
> believe (assuming you are using the DOM parser) ?
> 
> Even if you are using the SAX parser you can enable validation but it is kind
> of "ugly".
I am using the SAX parser and I was thinking about a DTD based
validation. I don't know if libxml supports anything like this.

[snip]

> > The Scrollkeeper files go into prefix/var/lib/scrollkeeper.
> 
> Umm - which scrollkeeper files are you talking about? Are these the OMF files?
> Shouldn't they go into prefix/share/scrollkeeper?
No, these are the files generated by Scrollkeeper and passed away to the
Help Browser. The OMF files are not moved by the current implementation.

> How are the OMF tags different than the OS locales?
OMF language tags are described here: 
http://www.landfield.com/rfcs/rfc1766.html

They are much broader and have a bit different format than the locales
(like en-US in OMF and en_US as OS locale).

Laszlo

[Scrollkeeper-devel] Re: Scrollkeeper code checked in

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

* laszlo kovacs (las...@su...) wrote at 00:02 on 17/10/00:
> Hi,
> 
> I checked in most of the implementation of the proposal from:

This is excellent news! :) I need to check out the code sometime soon. I was
just curious, but perhaps this should be announced to various Documentation
projects (just in case people want to throw in their comments and/or want to
contribute). Of course this should only be done when the code is in a "state"
to accept contributions.
 
> http://www.geocrawler.com/archives/3/5674/2000/8/0/4271223/
> 
> The following is not implemented:
> 
> - OMF file validation (I don't know how to do this so hints are welcome)

Umm - the OMF file is an XML file, correct? libxml should handle validation I
believe (assuming you are using the DOM parser) ? 

Even if you are using the SAX parser you can enable validation but it is kind
of "ugly". 

Basically I had to create an xmlParserCtxt (see gdb3html.c in the
"parse_file()" function on how I did it), turn on validation there, I think
the errors in validation are handled by the errorSAXFunc or something like
that. With gnome-db2html2 I "silence" these validation messages because:
1) We have DocBook SGML so we get a lot of 'error' messages due non-XML
compliance
2) I think validation in libxml 1.x only works to validate that the document
is proper XML (i.e. it doesn't validate the DTD). Check with Daniel Veillard
about this.

> - the extended content list is not implemented at all
> 
> The Scrollkeeper files go into prefix/var/lib/scrollkeeper.

Umm - which scrollkeeper files are you talking about? Are these the OMF files?
Shouldn't they go into prefix/share/scrollkeeper?

> We seem to have a problem with the locales. Namely OMF language tags
> from the metadata do not match the OS (Linux, Solaris etc) locales. At
> the moment the language tags are used to create the directories for each
> locale (e.g. prefix/var/lib/scrollkeeper/en for English). This should be
> changed to using the OS locale tags and Scrollkeeper should map the OMF
> language tags to the OS locales. I don't know if this is already
> implemented or not (at least for Linux as part of another project). I
> tried to find out from gnome#i18n with not much success. Please share
> any ideas.

How are the OMF tags different than the OS locales?

> There are a couple of small problems with the code that I know about and
> I am working on them, please give it a try and let me know what you
> think.

I'll take a look at my first 'free' opportunity. Thanks for finally checking
this in :)

Regards,
Ali

Re: [Scrollkeeper-devel] What about the distributions?

[Eric B. <eb...@cy...>]

Ali Abdin wrote:
> 
> There is a solution to this. Include a patch to the RPM that will
> "modify" the tarball to NOT run scrollkeeper-install (patches can be
> "attached" to RPMS (RedHat does it, but I do not know the technical side
> of how it is done)). This is the only "sound" solution I can think of.
> Debian dudes have their own patches to handle stuff :)

It's no clean solution and it can be tedious to prepare patches.

No the better is to let "make install" behave normally and use somehow
the partial database it built, either by ensuring it is copied in some
common directory but with a different name as the other database
snippets and that the help browser copes with a database spread over
many files, or that it gets merged together with the "real" database on
the user's hard disk. The first solution is the one that requires less
work for the distribution packager.

> Unfortunately, you have to ask yourself - Will application writers want
> to do this for their packages?

-- 
 Éric Bischoff   -   mailto:eb...@cy...
 __________________________________________________
                                           \^o~_.
     .~.                           ______  /( __ )
     /V\         Toys story         \__  \/  (  V
   //   \\                            \__| (__=v
  /(     )\                        |\___/     )
    ^^-^^                           \_____(  )
     Tux                        Konqui     \__=v
 __________________________________________________

Re: [Scrollkeeper-devel] What about the distributions?

[Eric B. <eb...@cy...>]

Dan Mueth wrote:
> 
> Thanks Eric.  It is very nice to get input from somebody who knows a lot
> about packaging.
> 
> I generally like this approach.  I have a few concerns:
> 
> 1) Say we have foo/app1/docs/app1_doc1 and foo/app2/docs/app2_doc1.  Then
> scrollkeeper-preinstall will overwrite $(DOCDIR)/doc-contents.omf twice
> and the final would only have the last doc listed. We could use ">>", but
> if $(DOCDIR)/doc-contents.omf happens to pre-exist, then we keep whatever
> crud was in it from before.

Forget about ">" and ">>". I used this notation without thinking. I just
wanted to state that the user's database had to be modified as a result.
Of course there should be more intelligence in that than shell
redirections.

> 2) As Ali pointed out, it seems to be hard to "have our cake and eat it
> too". Either 'make install' actually calls scrollkeeper-install on the
> local machine (as needed by tarball installs), or else it doesn't (as
> people who want to merely create an RPM but not install it would prefer).

No, it's not either... either. We must make the system work with only
"./configure; make; make install" AND provide a solution for packagers:

In the "install:" section of the Makefile a full, working installation
must be performed.

	AND

(We must provide a mechanism for merging the resulting database with a
bigger one

	OR

We must ensure that each packaged database has a different name, and
that the help browsers can cope with many database files, namely one per
package)

> The solution eludes me, although I'm sure this has been encountered many
> times in the past and there must be some nice solution.  A not too nice
> solution would be to have a separate target that the spec file calls
> instead of 'install'.  So we'd have 'make install' and 'make
> installforrpm'.

No, this goes against RPM's principle of "pristine sources". A real
"make install" should be performed. The thing is we must think to the
life of the resulting data to transfer them between the build system and
the install system.

>  This seems inelegant though.  Any RPM experts out there
> who would like to point out the solution?  Eric?  Also, I am trusting that
> deb's will not pose any new problems here.

Yes they will, just like Slackware's tgzs. The problem is not liked to
RPM technology, it's linked to the fact that the build system is not
necessarily the same as the install system.

I think you make too much confidence in debian's magic ;-).

> 3) Do deb's let you control where the deb installs?  The way we are doing
> things now, we are writing the path of the SGML file into the OMF metadata
> in the pre-install script. So if the installer has any power to change
> where things get installed (say under /share instead of
> /usr/local/share) then everything breaks.
> 
> 4) Did you literally mean to use the name "doc-contents.omf"?  This makes
> me think of the contents list which isn't really what this file is.

Well, I don't really see why the contents list should reside in a
different database. But this is another topic and maybe it's already
been discussed.

>  If I
> understand you (Eric), this is basically just a file with all the OMF
> files concatenated and possibly a bit more info if necessary.  Also, since
> there is a possibility of multiple packages installing docs into the same
> directory, we probably want to give them unique names. Perhaps
> $(DOCDIR)/<packagename>-docs.omf?

The problem if you choose the solution of the different names is that
the help browser at some point has to know where the real docs and the
OMF information are. And storing this information somewhere at "make
install" time *IS NOT* enough.

-- 
 Éric Bischoff   -   mailto:eb...@cy...
 __________________________________________________
                                           \^o~_.
     .~.                           ______  /( __ )
     /V\         Toys story         \__  \/  (  V
   //   \\                            \__| (__=v
  /(     )\                        |\___/     )
    ^^-^^                           \_____(  )
     Tux                        Konqui     \__=v
 __________________________________________________

Re: [Scrollkeeper-devel] What about the distributions?

[Eric B. <eb...@cy...>]

Ali Abdin wrote:
> 
> The problem arised when you are building RPMs (for example).
> 
> You do an 'rpm -ta file.tar.gz' - It starts building and then does a
> 'make install' to detect all the installed files. Unfortunately during
> this step you also do the 'scrollkeeper-install' thingy (so the file gets
> installed with scrollkeeper even though you were just BUILDING a package
> and not INSTALLING a package).
> 
> Icky situation, right?

As you say.

I feel less preaching in the desert now you described the problem in so
concise and understandable terms! Thanks for the contribution, Ali.

-- 
 Éric Bischoff   -   mailto:eb...@cy...
 __________________________________________________
                                           \^o~_.
     .~.                           ______  /( __ )
     /V\         Toys story         \__  \/  (  V
   //   \\                            \__| (__=v
  /(     )\                        |\___/     )
    ^^-^^                           \_____(  )
     Tux                        Konqui     \__=v
 __________________________________________________

Re: [Scrollkeeper-devel] What about the distributions?

[Eric B. <eb...@cy...>]

Ali Abdin wrote:
> 
> On Wed, 18 Oct 2000, Eric Bischoff wrote:
> 
> 
> Unfortunately - when people './configure;make;make install' they will
> miss out on this aspect.

You're right. This means the line in "install:" section should be enough
for updating the database on user's hard disk.

But you must also provide a mechanism to reflect those changes in the
database on packager's hard disk to the end-user's hard disk at
installation time.

Otherwise here is what will happen:

The packager installs the software on his hard disk. His database will
be created (since usually people package in /tmp, the database will be
created from scratch and only hold the entries for the software that is
being packaged).

So at the end the packager sees a new file, let's say
/tmp/usr/share/scrollkeeper/omf.xml. He has three choices:
- ignore the file, it means that he doesn't care about scrollkeeper or
doesn't want to or doesn't understand it or is too lazy to ask himself
the question... :-(
- put it into the %Files section of the specfile (or in the tgz on a
slackware). As soon as two packages use scrollkeeper there will be a
conflict UNLESS YOU GIVE EACH XML FILE A DIFFERENT, PACKAGE-RELATED NAME
- use a post-installation script that will merge this file with the
user's database on his hard disk.

So there are two opportunities for us:
1) Choose a naming convention that will ensure that each package has its
XML data stored in a separate file with a name of its own
2) Provide a kind of "scrollkeeper-merge" utility that will merge the
file on the packager's hard disk 

The first solution may hinder performance at database's browsing time.
The second solution means more work for the distributions :-( and may
hinder the distributions installlation time (post-installation scripts
are usually slow).

If those issues were discussed already, I apologize in advance, I had to
read quickly many old emails to get in pace with this list. Otherwise, I
think this issue is wort considering it.

> What you might need to do is to create some sort of
> system/cron-job/daemon in which scrollkeeper checks the local files
> installed - if it is missing it will remove them from its internal
> database.
>
> Otherwise you will need a big huge README in each project saying "please
> run scrollkeeper-install after 'make install' is done"

No, you're right, none of these are acceptable. We must update the
database in the Makefile AND provide a mechanism to packagers, should it
be have a clear naming convention for the slices of the database or a
post-installation script.

-- 
 Éric Bischoff   -   mailto:eb...@cy...
 __________________________________________________
                                           \^o~_.
     .~.                           ______  /( __ )
     /V\         Toys story         \__  \/  (  V
   //   \\                            \__| (__=v
  /(     )\                        |\___/     )
    ^^-^^                           \_____(  )
     Tux                        Konqui     \__=v
 __________________________________________________

Re: [Scrollkeeper-devel] What about the distributions?

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

On Wed, 18 Oct 2000, Dan Mueth wrote:

> 
> On Wed, 18 Oct 2000, Eric Bischoff wrote:
> 
> > After:
> > > --------------------------------
> > > In the Makefile:
> > > > install:
> > > >         cp foo.sgml $(DOCDIR)
> > > >         scrollkeeper-preinstall $(DOCDIR)/foo.sgml foo.omf > $(DOCDIR)/doc-contents.omf
> > >
> > > In the SPEC file:
> > > > %Post
> > > >         scrollkeeper-install $DOCDIR/doc-contents.omf
> > > >
> > > > %Postun
> > > >         scrollkeeper-uninstall $DOCDIR/doc-contents.omf
> > > >
> > > > %Files
> > > >	    $DOCDIR/doc-contents.omf
> > > --------------------------------
> 
> Thanks Eric.  It is very nice to get input from somebody who knows a lot
> about packaging.
> 
> I generally like this approach.  I have a few concerns:
> 
> 1) Say we have foo/app1/docs/app1_doc1 and foo/app2/docs/app2_doc1.  Then
> scrollkeeper-preinstall will overwrite $(DOCDIR)/doc-contents.omf twice
> and the final would only have the last doc listed. We could use ">>", but
> if $(DOCDIR)/doc-contents.omf happens to pre-exist, then we keep whatever
> crud was in it from before.
> 
> 2) As Ali pointed out, it seems to be hard to "have our cake and eat it
> too". Either 'make install' actually calls scrollkeeper-install on the
> local machine (as needed by tarball installs), or else it doesn't (as
> people who want to merely create an RPM but not install it would prefer).  
> The solution eludes me, although I'm sure this has been encountered many
> times in the past and there must be some nice solution.  A not too nice
> solution would be to have a separate target that the spec file calls
> instead of 'install'.  So we'd have 'make install' and 'make
> installforrpm'.  This seems inelegant though.  Any RPM experts out there
> who would like to point out the solution?  Eric?  Also, I am trusting that
> deb's will not pose any new problems here.

There is a solution to this. Include a patch to the RPM that will 
"modify" the tarball to NOT run scrollkeeper-install (patches can be 
"attached" to RPMS (RedHat does it, but I do not know the technical side 
of how it is done)). This is the only "sound" solution I can think of. 
Debian dudes have their own patches to handle stuff :) 

Unfortunately, you have to ask yourself - Will application writers want 
to do this for their packages?
 
> 3) Do deb's let you control where the deb installs?  The way we are doing
> things now, we are writing the path of the SGML file into the OMF metadata
> in the pre-install script. So if the installer has any power to change
> where things get installed (say under /share instead of
> /usr/local/share) then everything breaks.
> 
> 4) Did you literally mean to use the name "doc-contents.omf"?  This makes
> me think of the contents list which isn't really what this file is.  If I
> understand you (Eric), this is basically just a file with all the OMF
> files concatenated and possibly a bit more info if necessary.  Also, since
> there is a possibility of multiple packages installing docs into the same
> directory, we probably want to give them unique names. Perhaps
> $(DOCDIR)/<packagename>-docs.omf?
> 
> Dan
> 
> _______________________________________________
> Scrollkeeper-devel mailing list
> Scr...@li...
> http://lists.sourceforge.net/mailman/listinfo/scrollkeeper-devel
> 

Re: [Scrollkeeper-devel] What about the distributions?

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

On Wed, 18 Oct 2000, Eric Bischoff wrote:

> After:
> > --------------------------------
> > In the Makefile:
> > > install:
> > >         cp foo.sgml $(DOCDIR)
> > >         scrollkeeper-preinstall $(DOCDIR)/foo.sgml foo.omf > $(DOCDIR)/doc-contents.omf
> >
> > In the SPEC file:
> > > %Post
> > >         scrollkeeper-install $DOCDIR/doc-contents.omf
> > >
> > > %Postun
> > >         scrollkeeper-uninstall $DOCDIR/doc-contents.omf
> > >
> > > %Files
> > >	    $DOCDIR/doc-contents.omf
> > --------------------------------

Thanks Eric.  It is very nice to get input from somebody who knows a lot
about packaging.

I generally like this approach.  I have a few concerns:

1) Say we have foo/app1/docs/app1_doc1 and foo/app2/docs/app2_doc1.  Then
scrollkeeper-preinstall will overwrite $(DOCDIR)/doc-contents.omf twice
and the final would only have the last doc listed. We could use ">>", but
if $(DOCDIR)/doc-contents.omf happens to pre-exist, then we keep whatever
crud was in it from before.

2) As Ali pointed out, it seems to be hard to "have our cake and eat it
too". Either 'make install' actually calls scrollkeeper-install on the
local machine (as needed by tarball installs), or else it doesn't (as
people who want to merely create an RPM but not install it would prefer).  
The solution eludes me, although I'm sure this has been encountered many
times in the past and there must be some nice solution.  A not too nice
solution would be to have a separate target that the spec file calls
instead of 'install'.  So we'd have 'make install' and 'make
installforrpm'.  This seems inelegant though.  Any RPM experts out there
who would like to point out the solution?  Eric?  Also, I am trusting that
deb's will not pose any new problems here.

3) Do deb's let you control where the deb installs?  The way we are doing
things now, we are writing the path of the SGML file into the OMF metadata
in the pre-install script. So if the installer has any power to change
where things get installed (say under /share instead of
/usr/local/share) then everything breaks.

4) Did you literally mean to use the name "doc-contents.omf"?  This makes
me think of the contents list which isn't really what this file is.  If I
understand you (Eric), this is basically just a file with all the OMF
files concatenated and possibly a bit more info if necessary.  Also, since
there is a possibility of multiple packages installing docs into the same
directory, we probably want to give them unique names. Perhaps
$(DOCDIR)/<packagename>-docs.omf?

Dan

Re: [Scrollkeeper-devel] What about the distributions?

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

On Wed, 18 Oct 2000, laszlo kovacs wrote:

> > Unfortunately - when people './configure;make;make install' they will
> > miss out on this aspect.
> > 
> > What you might need to do is to create some sort of
> > system/cron-job/daemon in which scrollkeeper checks the local files
> > installed - if it is missing it will remove them from its internal
> > database.
> > 
> > Otherwise you will need a big huge README in each project saying "please
> > run scrollkeeper-install after 'make install' is done"
> 
> Can each project have in its Makefile a section that checks for
> Scrollkeeper and if it's installed then installs the docs for
> Scrollkeeper also (same for uninstall)? I guess the problem is the large
> number of packages and distributors, but it can be done in time if the
> system (Scrollkeeper and the Help Browser) is good so distributors see
> it is better to support it.

The problem arised when you are building RPMs (for example).

You do an 'rpm -ta file.tar.gz' - It starts building and then does a 
'make install' to detect all the installed files. Unfortunately during 
this step you also do the 'scrollkeeper-install' thingy (so the file gets 
installed with scrollkeeper even though you were just BUILDING a package 
and not INSTALLING a package). 

Icky situation, right?
 
> Laszlo
> 

Re: [Scrollkeeper-devel] What about the distributions?

[laszlo k. <las...@su...>]

> Unfortunately - when people './configure;make;make install' they will
> miss out on this aspect.
> 
> What you might need to do is to create some sort of
> system/cron-job/daemon in which scrollkeeper checks the local files
> installed - if it is missing it will remove them from its internal
> database.
> 
> Otherwise you will need a big huge README in each project saying "please
> run scrollkeeper-install after 'make install' is done"

Can each project have in its Makefile a section that checks for
Scrollkeeper and if it's installed then installs the docs for
Scrollkeeper also (same for uninstall)? I guess the problem is the large
number of packages and distributors, but it can be done in time if the
system (Scrollkeeper and the Help Browser) is good so distributors see
it is better to support it.

Laszlo

Re: [Scrollkeeper-devel] What about the distributions?

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

On Wed, 18 Oct 2000, Eric Bischoff wrote:

> laszlo kovacs wrote:
> > 
> > Hi Eric,
> > 
> > Thanks for this, but I don't know much about packaging in general so I
> > don't have much clue about what you are suggesting.
> 
> Let me explain you.
> 
> In Linux world, it's not the same person that programs the software and
> that packages the software, unlike in Windows world.
> 
> The software programmer produces a Makefile. This makefile has an
> "install" section that is enough to install the software locally.
> 
> The packager takes this makefile, runs it on his own computer, and sees
> what comes of it. He usually gets a set of files that will go into some
> list and be distributed.
> 
> The problem appears when the makefile does not simply create a
> standalone file, but *modifies* a centralized database. That's exactly
> what will happen with scrollkeeper-install. There's no resulting file
> that can simply be thrown into the distribution: the result is a
> *portion* of a file. So the packager puts the corresponding instructions
> in what is called a "post-installation" script. The packager builds the
> package on his own computer, but he knows the post-installation script
> will be run on the end-user's computer.
> 
> This is why Dan's setup would simply not have worked.
> 
> The most efficient solution and that will not require too much changes
> in existing makefiles and specfiles is to split the script in two:
> - one part, called in "install" section of the makefile, gathers all the
> OMF info into a "metainformation snippet"
> - another part, called in the post-installation script of the specfile
> (or whatever equivalent), merges this snippet with the existing
> database, which holds both the contents list and the OMF information.
> 
> > Anyway the install
> > and uninstall scripts are very easy to change as they are small so any
> > change can be done quickly.
> 
> Better so. Here is in short what I propose.
> 
> Before:
> > --------------------------------
> > In the Makefile:
> > > install:
> > >         cp foo.sgml $(DOCDIR)
> > >         cp foo-omf $(DOCDIR)
> > >         scrollkeeper-install $(DOCDIR)/foo.sgml $(DOCDIR)/foo-omf
> > --------------------------------
> 3 lines *per document* in the Makefile
> 
> After:
> > --------------------------------
> > In the Makefile:
> > > install:
> > >         cp foo.sgml $(DOCDIR)
> > >         scrollkeeper-preinstall $(DOCDIR)/foo.sgml foo.omf > $(DOCDIR)/doc-contents.omf
> >
> > In the SPEC file:
> > > %Post
> > >         scrollkeeper-install $DOCDIR/doc-contents.omf
> > >
> > > %Postun
> > >         scrollkeeper-uninstall $DOCDIR/doc-contents.omf
> > >
> > > %Files
> > >	    $DOCDIR/doc-contents.omf
> > --------------------------------
> 2 lines *per document* in the makefile
> 3 lines *for all documents* in the specfile


Unfortunately - when people './configure;make;make install' they will 
miss out on this aspect.

What you might need to do is to create some sort of 
system/cron-job/daemon in which scrollkeeper checks the local files 
installed - if it is missing it will remove them from its internal 
database.

Otherwise you will need a big huge README in each project saying "please 
run scrollkeeper-install after 'make install' is done"

[Scrollkeeper-devel] What about the distributions?

[Eric B. <eb...@cy...>]

laszlo kovacs wrote:
> 
> Hi Eric,
> 
> Thanks for this, but I don't know much about packaging in general so I
> don't have much clue about what you are suggesting.

Let me explain you.

In Linux world, it's not the same person that programs the software and
that packages the software, unlike in Windows world.

The software programmer produces a Makefile. This makefile has an
"install" section that is enough to install the software locally.

The packager takes this makefile, runs it on his own computer, and sees
what comes of it. He usually gets a set of files that will go into some
list and be distributed.

The problem appears when the makefile does not simply create a
standalone file, but *modifies* a centralized database. That's exactly
what will happen with scrollkeeper-install. There's no resulting file
that can simply be thrown into the distribution: the result is a
*portion* of a file. So the packager puts the corresponding instructions
in what is called a "post-installation" script. The packager builds the
package on his own computer, but he knows the post-installation script
will be run on the end-user's computer.

This is why Dan's setup would simply not have worked.

The most efficient solution and that will not require too much changes
in existing makefiles and specfiles is to split the script in two:
- one part, called in "install" section of the makefile, gathers all the
OMF info into a "metainformation snippet"
- another part, called in the post-installation script of the specfile
(or whatever equivalent), merges this snippet with the existing
database, which holds both the contents list and the OMF information.

> Anyway the install
> and uninstall scripts are very easy to change as they are small so any
> change can be done quickly.

Better so. Here is in short what I propose.

Before:
> --------------------------------
> In the Makefile:
> > install:
> >         cp foo.sgml $(DOCDIR)
> >         cp foo-omf $(DOCDIR)
> >         scrollkeeper-install $(DOCDIR)/foo.sgml $(DOCDIR)/foo-omf
> --------------------------------
3 lines *per document* in the Makefile

After:
> --------------------------------
> In the Makefile:
> > install:
> >         cp foo.sgml $(DOCDIR)
> >         scrollkeeper-preinstall $(DOCDIR)/foo.sgml foo.omf > $(DOCDIR)/doc-contents.omf
>
> In the SPEC file:
> > %Post
> >         scrollkeeper-install $DOCDIR/doc-contents.omf
> >
> > %Postun
> >         scrollkeeper-uninstall $DOCDIR/doc-contents.omf
> >
> > %Files
> >	    $DOCDIR/doc-contents.omf
> --------------------------------
2 lines *per document* in the makefile
3 lines *for all documents* in the specfile

-- 
 Éric Bischoff   -   mailto:eb...@cy...
 __________________________________________________
                                           \^o~_.
     .~.                           ______  /( __ )
     /V\         Toys story         \__  \/  (  V
   //   \\                            \__| (__=v
  /(     )\                        |\___/     )
    ^^-^^                           \_____(  )
     Tux                        Konqui     \__=v
 __________________________________________________

[Scrollkeeper-devel] Scrollkeeper code checked in

[laszlo k. <las...@su...>]

Hi,

I checked in most of the implementation of the proposal from:

http://www.geocrawler.com/archives/3/5674/2000/8/0/4271223/

The following is not implemented:

- OMF file validation (I don't know how to do this so hints are welcome)
- the extended content list is not implemented at all

The Scrollkeeper files go into prefix/var/lib/scrollkeeper.

We seem to have a problem with the locales. Namely OMF language tags
from the metadata do not match the OS (Linux, Solaris etc) locales. At
the moment the language tags are used to create the directories for each
locale (e.g. prefix/var/lib/scrollkeeper/en for English). This should be
changed to using the OS locale tags and Scrollkeeper should map the OMF
language tags to the OS locales. I don't know if this is already
implemented or not (at least for Linux as part of another project). I
tried to find out from gnome#i18n with not much success. Please share
any ideas.

There are a couple of small problems with the code that I know about and
I am working on them, please give it a try and let me know what you
think.

Thanks,

Laszlo

Re: [Scrollkeeper-devel] Scrollkeeper License

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

On Mon, 9 Oct 2000, Dan Mueth wrote:

> 
> On Mon, 9 Oct 2000, Dan Mueth wrote:
> 
> > Another solution would be to contact the original authors of the borrowed
> > code and get their approval to relicense these sections under LGPL. (If we
> > keep any non-trivial code, we pretty much have to do this if we want
> > ScrollKeeper under LGPL.)  I am cc'ing Jonathan and Ali, who I believe are
> > the only two copyright holders on toc-elements.c.
> 
> I just spoke with Jonathan on IRC and he gave his blessing.  Ali?

I do not wish to 'generically' re-license the code. I am willing to give 
the ScrollKeeper project explicit permission to use the code under the 
terms of the LGPL (but not any other project). I hope jrb agrees to this.

Regards,
Ali

Re: [Scrollkeeper-devel] Scrollkeeper License

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

On Mon, 9 Oct 2000, laszlo kovacs wrote:

> Hi,
> 
> It seems to be a problem (to me at least) what the Scrollkeeper license
> is going to be. We talked with Dan about this a bit and LGPL seemed
> better than GPL as Scrollkeeper might be used by proprietary help
> browsers as well. When I started developing the code that I used to
> extract the Table Of Contents from Docbook files I looked at
> gnome-db2html in Nuatilus because there is a similar functionality
> there. I took that code, removed everything I didnt need and added new
> functionality. What I essentially kept from that code was how to use the
> SAX interface of libxml. If I copyright my code to people who developed
> gnome-db2html then my understanding is that Scrollkeeper has to be GPL
> as gnome-db2html is also GPL. 
> 
> Another option is to not copyright to gnome-db2html authors, but mention
> them in the THANKS file, this way the license could be LGPL. This could
> be backed up by the fact that there is only one way to use the SAX
> interface anyway and I happened to learn that from GPL code. To be
> mentioned that I also kept the stack based approach of the
> implementation (Ali would know what I am talking about).

I'm no law expert - but I don't think that would fly in a court (i.e. 
you're not "clean room" and it can be argued that you re-licensed code 
without the AUTHORS permission). Not that I'd sue you or Sun :P
 
> Or maybe there are other licensing issues to be considered or I just
> dont see the whole picture.
> 
> The reason I am raising this is that my understanding is that once the
> code is made public under GPL, this can not be changed so we probably
> need to clarify the license before that.
> 
> What do people think?

Well - since gnome-db2html2 is an /application/ and not a library, I have 
an objection to re-licensing it under the LGPL.

Personally though, I have no objection to giving the ScrollKeeper 
explicit permission to use this code under the LGPL in their 'product. 
This is of course based on the assumption that ScrollKeeper is LGPL'd.

I would not want to re-license gnome-db2html2 so companies can use it for 
their own interests, but I do not mind the ScrollKeeper project from 
using it if they wish.

Unfortunately, I can not make this decision alone. jr...@re... is the 
original author or this product so he must be consulted too. Also John 
Fleck has contributed some patches - I wonder if he should be included 
too (his contributions are 'more than 10 lines' (albeit, I haven't 
integrated his patches yet (and I usually modify these patches myself))

Regards,
Ali

Re: [Scrollkeeper-devel] Scrollkeeper License

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

On Mon, 9 Oct 2000, Dan Mueth wrote:

> Another solution would be to contact the original authors of the borrowed
> code and get their approval to relicense these sections under LGPL. (If we
> keep any non-trivial code, we pretty much have to do this if we want
> ScrollKeeper under LGPL.)  I am cc'ing Jonathan and Ali, who I believe are
> the only two copyright holders on toc-elements.c.

I just spoke with Jonathan on IRC and he gave his blessing.  Ali?

Dan

Re: [Scrollkeeper-devel] Scrollkeeper License

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

Another solution would be to contact the original authors of the borrowed
code and get their approval to relicense these sections under LGPL. (If we
keep any non-trivial code, we pretty much have to do this if we want
ScrollKeeper under LGPL.)  I am cc'ing Jonathan and Ali, who I believe are
the only two copyright holders on toc-elements.c.

Dan

On Mon, 9 Oct 2000, laszlo kovacs wrote:

> Hi,
> 
> It seems to be a problem (to me at least) what the Scrollkeeper license
> is going to be. We talked with Dan about this a bit and LGPL seemed
> better than GPL as Scrollkeeper might be used by proprietary help
> browsers as well. When I started developing the code that I used to
> extract the Table Of Contents from Docbook files I looked at
> gnome-db2html in Nuatilus because there is a similar functionality
> there. I took that code, removed everything I didnt need and added new
> functionality. What I essentially kept from that code was how to use the
> SAX interface of libxml. If I copyright my code to people who developed
> gnome-db2html then my understanding is that Scrollkeeper has to be GPL
> as gnome-db2html is also GPL. 
> 
> Another option is to not copyright to gnome-db2html authors, but mention
> them in the THANKS file, this way the license could be LGPL. This could
> be backed up by the fact that there is only one way to use the SAX
> interface anyway and I happened to learn that from GPL code. To be
> mentioned that I also kept the stack based approach of the
> implementation (Ali would know what I am talking about).
> 
> Or maybe there are other licensing issues to be considered or I just
> dont see the whole picture.
> 
> The reason I am raising this is that my understanding is that once the
> code is made public under GPL, this can not be changed so we probably
> need to clarify the license before that.
> 
> What do people think?
> 
> Laszlo

[Scrollkeeper-devel] Scrollkeeper License

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

Hi,

It seems to be a problem (to me at least) what the Scrollkeeper license
is going to be. We talked with Dan about this a bit and LGPL seemed
better than GPL as Scrollkeeper might be used by proprietary help
browsers as well. When I started developing the code that I used to
extract the Table Of Contents from Docbook files I looked at
gnome-db2html in Nuatilus because there is a similar functionality
there. I took that code, removed everything I didnt need and added new
functionality. What I essentially kept from that code was how to use the
SAX interface of libxml. If I copyright my code to people who developed
gnome-db2html then my understanding is that Scrollkeeper has to be GPL
as gnome-db2html is also GPL. 

Another option is to not copyright to gnome-db2html authors, but mention
them in the THANKS file, this way the license could be LGPL. This could
be backed up by the fact that there is only one way to use the SAX
interface anyway and I happened to learn that from GPL code. To be
mentioned that I also kept the stack based approach of the
implementation (Ali would know what I am talking about).

Or maybe there are other licensing issues to be considered or I just
dont see the whole picture.

The reason I am raising this is that my understanding is that once the
code is made public under GPL, this can not be changed so we probably
need to clarify the license before that.

What do people think?

Laszlo

[Scrollkeeper-devel] Scrollkeeper Contents List Code

[laszlo k. <las...@su...>]

Dan,

You know that people from Sun Microsystems joined into this project
because of the Nautilus Help Browser that would be the new help browser
in Gnome. There are three people working on it, two Sun engineers and
Cgabriel (from GDP?). Cgabriel was supposed to implement a key part of
it. At this stage both Sun engineers mostly completed what they were
supposed to do and they are stuck waiting for Cgabriel's code to get
into CVS. This has been like this for almost a week. I know that this
project is supposed to be independent from Gnome and Nautilus, but for
us it is not. Considering the current situation I suggest that engineers
from Sun write the part that Cgabriel was supposed to do as Nautilus
deadlines are closing down on us and we do not seem to step any further.

Laszlo

Re: [Scrollkeeper-devel] Re: [Dewey-devel] ScrollKeeper mailing list

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

On Tue, 19 Sep 2000, Ali Abdin wrote:

> > I will subscribe everybody on dewey-devel to scrollkeeper-devel in just a
> > few minutes.  Everybody should get an email notification that they are
> > subscribed.  If you do not get notification in the next couple hours,
> > please subscribe yourself at: 
> > http://lists.sourceforge.net/mailman/listinfo/scrollkeeper-devel
> 
> Please make sure you destroy/annihalate the old mailing list. I hate 
> old/dead mailing lists which occasionaly get me spam messages

I disabled everybody on dewey-devel from getting email from that list.

From now on please send all mail to: 
      scr...@li...

Dan

Re: [Scrollkeeper-devel] Re: [Dewey-devel] ScrollKeeper mailing list

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

On Mon, 18 Sep 2000, Dan Mueth wrote:
> On Tue, 19 Sep 2000, Mark Ovens wrote:
> 
> > I notice that ScrollKeeper is the new name and that the Website is
> > back up. One question: the new mailing, scrollkeeper-devel, doesn't
> > list the 20 subscribers to the original dewey list. Do we have to
> > re-subscribe or will we be automatically transferred?
> 
> Wow - You are fast.  This list was just created a couple hours ago ;)
> 
> Dewey has changed its name to ScrollKeeper.  The new web page is at
> http://ScrollKeeper.sourceforge.net/
> 
> I will subscribe everybody on dewey-devel to scrollkeeper-devel in just a
> few minutes.  Everybody should get an email notification that they are
> subscribed.  If you do not get notification in the next couple hours,
> please subscribe yourself at: 
> http://lists.sourceforge.net/mailman/listinfo/scrollkeeper-devel

Please make sure you destroy/annihalate the old mailing list. I hate 
old/dead mailing lists which occasionaly get me spam messages

[Scrollkeeper-devel] Re: [Dewey-devel] ScrollKeeper mailing list

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

On Tue, 19 Sep 2000, Mark Ovens wrote:

> I notice that ScrollKeeper is the new name and that the Website is
> back up. One question: the new mailing, scrollkeeper-devel, doesn't
> list the 20 subscribers to the original dewey list. Do we have to
> re-subscribe or will we be automatically transferred?

Wow - You are fast.  This list was just created a couple hours ago ;)

Dewey has changed its name to ScrollKeeper.  The new web page is at
http://ScrollKeeper.sourceforge.net/

I will subscribe everybody on dewey-devel to scrollkeeper-devel in just a
few minutes.  Everybody should get an email notification that they are
subscribed.  If you do not get notification in the next couple hours,
please subscribe yourself at: 
http://lists.sourceforge.net/mailman/listinfo/scrollkeeper-devel

Dan

[Scrollkeeper-devel] ScrollKeeper mailing list

[Mark O. <ma...@fr...>]

I notice that ScrollKeeper is the new name and that the Website is
back up. One question: the new mailing, scrollkeeper-devel, doesn't
list the 20 subscribers to the original dewey list. Do we have to
re-subscribe or will we be automatically transferred?

-- 
		4.4 - The number of the Beastie
________________________________________________________________
51.44°N  FreeBSD - The Power To Serve http://www.freebsd.org
2.057°W  My Webpage http://ukug.uk.freebsd.org/~mark
mailto:ma...@fr...                http://www.radan.com