-------------------------------------------------------------------------------
-                                                                             -
-   KOffice Storage Format Specification - first draft                        -
-                                                                             -
-   by Werner, last changed: 990730 by Werner                                 -
-                                                                             -
-------------------------------------------------------------------------------

The purpose of this document is to define a common KOffice Storage Structure.
Torben, Reggie, and all the others agreed on storing embedded KOffice Parts
and binary data (e.g. pictures, movies, sounds) via a simple gzipped-tar-
structure. Yesterday (990730) Torben "released" KTar which will probably be
moved to kio soon (kio_tar or something). At the moment you can fetch it from
http://www.informatik.uni-frankfurt.de/~weis/ktar.cpp .

1) Name of the KOffice Files:
I think it is important to show that the file is a tgz-archieve, so I suggest
using filenames like "MyLetter.kwd.tgz", "Sales.ksp.tgz", or "Meeting.kpr.tgz".

2) Internal Structure:
I don't like theoretic explanations so I'd give a simple example: Assume you
have to write a lab-report. Coincidence? I think not >:) You surely will have
some text, the readings, some formulas and a few pictures (e.g. circiut
diagram,...).
The main document will be a KWord-file. In this file you embed some KSpread-
tables, some KDiagram-charts, the KFormulas, and some picture-frames. You save
the whole crap and name it "lab-report.kwd.tgz." Now I'd like to suggest the
internal structure of this file:

lab-report(DIR) +- lab-report.kwd(FILE)
                |
                |- KSpread(DIR) +- part0.ksp(FILE)
                |                \ part1.ksp(FILE)
                |
                |- KDiagram(DIR) +- part2.kdg(FILE)
                |                |- ...
                |                 \ part8.kdg(FILE)
                |
                |- KFormula(DIR) +- part9.kfa(FILE)
                |
                |- Pictures(DIR) +- picture0.jpg(FILE)
                |                |- picture1.png(FILE)
                |                 \ picture2.wmf(FILE)
                |
                 \ summary.ko(FILE)

I'm not quite sure if we should go for a "flat" directory structure (one single
dir containing all the files) or if we should do it like I showed above.
BTW: I don't know if it is possible to store a KDiagramm/KFormula, yet.
Another thing to discuss is if we need a "summary.ko" file. This could e.g.
contain the author's name, the dates,... This information is stored at least
in the kwd-files (I don' know about the other formats), but some nice layout
for this information would be a nifty feature. Let me show what I mean:

Format of summary.ko:

Author: Werner Trobin
Date of creation: 30.08.1999
Last change: 30.08.1999 
Files in this archieve (Comment):
lab-report.kwd                  (main document)
KSpread/part0.ksp               (PI-control, not optimized)
KSpread/part1.ksp               (PI-control, optimized)
KDiagram/part2.kdg              (Frequenzgang (sorry, no good dictionary))
KDiagram/part3.kdg              (Sprungantwort (ditto))
...
KFormula/part9.kfa              (Uebertragungsfunktion (no dictionary))   
...
Pictures/picture2.wmf           (circuit diagram)
                        
This file (summary.ko) can be edited via a nice Dialog box.

3) Accessing files:
I think it is the easiest way to address the files either absolute or relative
(e.g. "/KSpread/part0.ksp", or "picture3.jgp"). If ktar.cpp ensures that the
names are unique one could even address the files via the plain name.


This is the first draft of this document. Please correct the typos (maybe one
can even translate "Frequenzgang" and so on) and let me know what you think of
this (and suggest improvements :)

I suggest discussing this topic on koffice@kde.org, but you can also send some
private mail (flames :) to wtrobin@carinthia.com

Thank you for your attention,
Werner