Shared documentation system
schumacher at kde.org
Wed Dec 17 11:28:16 EET 2003
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
> > 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>
More information about the xdg