Shared documentation system

[Laszlo Kovacs]

On Wed, 2003-12-17 at 09:28, Cornelius Schumacher wrote:
> On Thursday 11 December 2003 20:36, Shaun McCance wrote:
> >
> > Sure, it's more difficult to work with than it ought to be.  And
that is
> > something that I'm trying to address.  But distributors that build
and
> > ship ScrollKeeper really have no excuse.
> 
> One of the main problems of Scrollkeeper is that it requires merging
the 
> documentation meta information after installation of new documentation
and 
> unmerging after deinstallation. This is bad for packaging because it
requires 
> running extra scripts and creates files which don't correspond to a
certain 
> single package. A new documentation meta information standard should
address 
> this problem.

The problem is that it is not obvious what the right balance is. When
documentation is created and deployed some tasks have to always be done
during development or at build time or at installation time or at
runtime.

Scrollkeeper is a middleware that tries to make everybody's job a bit
easier and preprocess data so that things are reasonably fast at
runtime.

Two examples:

1. It uses the metadata to insert a document in a category list that is
used by the help browser. If this is not done then the help browser has
to do it at runtime which will slow things down.

2. It extracts TOC and index from Docbook files into a very simple
unified xml format that can be used by help browsers to display/search
TOC and index. If a middleware like Scrollkeeper is eliminated then info
like TOC and index will either have to be extracted during runtime (will
be slow and the help browser has to be able to parse a large number of
formats) or delivered as metadata (the developer needs build tools to
create them). I think Shaun advocates for this type of information being
delivered as metadata, however it might be difficult to convince people
to comply with a number of extra build requirements if they want their
docs displayed (we saw this when Scrollkeeper was introduced a couple of
years back into Gnome).

I think it is important to know that if we throw out the middleware
concept then either developers will need to do much more or runtime will
be slower. At the same time I know that the middleware idea has its own
issues as well.

Laszlo