[Scrollkeeper-devel] Registering documents with ScrollKeeper

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

We are back to our favorite debate... "How should a package register its
documentation with scrollkeeper?"

Let me try to catch people up with our previous plans:

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)


Plan #2
-------
We use a build-time script which (a) writes the paths of the docs into
the omf files, and (b) merges the omf files together.  Then we call a
post-install script:

scrollkeeper-install <bigomffile>

Pro's: We only have one post-install script, even if we have many
documents.

Con's: This solution breaks if the package is not installed in its default
location since the doc paths are written into <bigomffile> at build
time.  There are small problems with the build-time script (we called it
scrollkeeper-preinstall).

This solution made things much simpler for the developer than #1, but not
as simple as #3 below.  It seems to share the same problem as #3, but is
more complex.

Plan #3 
------- 

A build-time script copies each omf file to a new file which will be
installed, modifying the URI. We require all packages to install their OMF
files into one of one or more standard paths.  After installation,
modification, or uninstallation of an OMF file and doc, a script is called
(scrollkeeper-update) which looks in these OMF paths, detects what has
changed, and acts accordingly.

Pro's: Very simple for developers.  Although it still uses a post-install
script, it is a completely trivial line to add.

Con's: This solution is broken if the package is not installed in its
default location.

-----------------

Generally, scrollkeeper needs to know when an OMF file has been added,
modified, or removed. It also needs to know which document the OMF file
describes.  (The OMF file has a tag which should hold the location of the
doc.)

I think we really want to avoid any solution which requires one
post-install script per doc (like #1 above), since this becomes a huge
burden for packages with more than one doc and people are likely to forget
to update things after adding each new doc.

The problem with the simpler solutions is that they generally require the
paths to be merged into the OMF files at build time which means the paths
tend to be wrong if people change where things get installed at install
time.

Would it be possible to use Plan #3, but have scrollkeeper-install take a
parameter which describes the prefix the document is installed under?  
This way scrollkeeper would know if the user is installing the docs under
a different path and could still find them?  

I'm still looking for Plan #4 (The Perfect Plan), so if you have any ideas
please post them.

Dan