Re: [Scrollkeeper-devel] Registering documents with ScrollKeeper

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

On Wed, 15 Nov 2000, Nik Clayton wrote:

> On Tue, Nov 14, 2000 at 11:05:09AM -0600, Dan Mueth wrote:
> > Plan #1
> > -------
> > After the document and OMF file are installed, scrollkeeper is informed
> > (by way of a post-install script) where the document and the OMF file
> > are at with something like:
> > 
> > scrollkeeper-install <docfile> <omffile>
> > 
> > Pro's: If people change where things get installed during installation of
> > the package (and after the package is built), things do not break.
> > 
> > Con's: This requires one post-install script per document in the
> > package.  It also requires that the packager keep track of the appropriate
> > path variables.  (ie. it is a substantial burden on packagers)
> 
> By "per document", do you mean "per document", or do you mean "per file 
> that might make up a document, such as if a FAQ is broken up in to 15
> different files"?

I mean "per document".  So a directory full of HTML files and PNG's which
comprise one single document is just considered one document, and it has
one OMF file which points to the main file for the document (perhaps
/usr/share/doc/<appname>/<local>/<docname>/index.html.)

> If it's the former, I really don't see this being a huge problem.  It's
> exactly what package maintainers have to do at the moment when they 
> install a library, and need to run ldconfig afterwards.

I'm glad you don't think this would be a problem.  Would anybody like to
argue that it would be a problem?  (Eric?)

I don't have a very good feeling for how much packagers are willing to
do.  The argument Eric made was that this would be too much to expect from
packagers.

> In addition, I would expect most documentation for an application is
> going to install in a subdirectory that's specific to that application.
> So the package maintainer should be able to get away with something like
> 
>     scrollkeeper-update /usr/local/share/doc/app-name
> 
> and let scrollkeeper-update work out what to pull in.

For this to work we would have to require each OMF file lives in the same
directory as the document it describes (or possibly have a reliable
relative path to the document).  Then we just point scrollkeeper-update to
all directories where doc/omf pairs are installed.  We would still need
one call (or one argument) to the script per directory we install docs in.  
But this is just an incremental improvement over Plan #1, at the cost of
requiring the OMF file live in the same directory as the document.  

I suspect that generally each document (and each locale) will have its own
directory.  For something like gnome-applets, which is admittedly
atypical, this will be 300 or more distinct directories once the
translations are done.  So we would have to loop over the directories as
your info file example below does.  

> As long as it's not more complicated than this process to manage info files,
> we should be OK;
> 
>     http://www.freebsd.org/porters-handbook/porting-info.html

Dan