Shared documentation system

[Cornelius Schumacher]

On Wednesday 17 December 2003 13:58, Laszlo Kovacs wrote:
> On Wed, 2003-12-17 at 09:28, Cornelius Schumacher wrote:
> >
> > 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.

Yes, it's not easy to find the right balance. As it also depends on factors 
like how much documentation you have and how fast your computer is it might 
be even impossible to find a solution for everybody.

> 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.

Yes, KHelpcenter does this at runtime, and yes, this slows things down. On the 
other hand this is something which can be addressed by optimizations like 
caching, delayed loading etc, or might even be no problem at all for people 
with fast machines.

Doing this at install time creates a structural problem for packaging which 
can't be addressed by optimizations. That's the reason why I would prefer the 
run-time solution here.

> 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).

Extracting this kind of information at run-time is a nice solution, because it 
doesn't need any information to be duplicated. KHelpcenter does this for 
Docbook and it seems to be reasonably fast. Delivering this meta information 
separately poses the danger of inconsistencies and adds additional build 
complexity for everybody providing documentation.

That the help browser needs to be able to parse a large number of formats is 
true, but as the code required to extract the TOC is required in any case, 
independent of if you do this extraction at run-time, build-time or 
install-time, this might not be a problem.

> 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.

I think we have to set our priorities on making life as easy as possible for 
developers and packagers of apps who want their documentation to appear in 
the help browser. If that requires extra complexity in the help browser 
that's a well-localized problem which can be solved more easily than people 
not accepting the requirements of the help system.

-- 
Cornelius Schumacher <schumacher at kde.org>