Shared documentation system
Laszlo.Kovacs at Sun.COM
Wed Dec 17 15:00:13 EET 2003
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
> > something that I'm trying to address. But distributors that build
> > ship ScrollKeeper really have no excuse.
> One of the main problems of Scrollkeeper is that it requires merging
> documentation meta information after installation of new documentation
> unmerging after deinstallation. This is bad for packaging because it
> running extra scripts and creates files which don't correspond to a
> single package. A new documentation meta information standard should
> 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
Scrollkeeper is a middleware that tries to make everybody's job a bit
easier and preprocess data so that things are reasonably fast at
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.
More information about the xdg