Shared documentation system

[Cornelius Schumacher]

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.

> > Well, there is the specification at
> > http://www.freedesktop.org/Standards/desktop-entry-spec. If this isn't
> > sufficient we should fix that.
>
> All right, if that's the only specification on this format, then I stand
> by my comment.  That's very under-specified.

What exactly is missing? This standard is widely used, so if it has 
shortcomings we have to fix them anyway.

> Having special-case semantics for translations and formattings is sorely
> insufficient.  You can't anticipate everything people might do to their
> documents.  In fact, the simple special-casing I've seen doesn't even
> handle formattings very nicely.  How do I distinguish between a one-page
> HTML build and a multiple-page HTML build?

In terms of meta data I would create different meta info files for different 
formattings. The same for versions, revisisons, translations, whatever. The 
reason for that is that each "copy" of a document can generally installed 
independently of the other copies. So each copy has to bring its own 
metainformation. Otherwise you either would have meta data in the system for 
documentation which actually isn't present or you would have to merge meta 
information which comes with a copy into the meta file describing the whole 
document. That's not desirable as already said above.

> Provide a generalized mechanism to encode variations of a document, and
> let the metadata speak for itself.  Otherwise you aritifically restrict
> the utility of the system.

My suggestion would be to use a similar mechanism as we use it for 
translations in KHelpcenter: Each variation gets an own meta info file which 
in some way has a reference to what document it is a variation of. Doing it 
by adding a suffix to the filename has the advantage that variations of a 
document can be recognized without opening the file, but this could also be 
done by some tag inside the file.

-- 
Cornelius Schumacher <schumacher at kde.org>