diff options
Diffstat (limited to 'src/projects/kostore/SPEC')
| -rw-r--r-- | src/projects/kostore/SPEC | 122 |
1 files changed, 122 insertions, 0 deletions
diff --git a/src/projects/kostore/SPEC b/src/projects/kostore/SPEC new file mode 100644 index 0000000..e72286a --- /dev/null +++ b/src/projects/kostore/SPEC @@ -0,0 +1,122 @@ +------------------------------------------------------------------------------- +- - +- KOffice Storage Format Specification - Version 2.3 - +- - +- by Werner, last changed: 20020306 by Werner Trobin - +- - +- History : - +- Version 1.0 : binary store - +- Version 2.0 : tar.gz store - +- Version 2.1 : cleaned up - +- version 2.2 : shaheed Put each part into its own directory to allow - +- one filter to easily embed the results of another - +- and also to have its own documentinfo etc. - +- Added description of naming convention. - +- Version 2.3 : werner Allow the usage of relative links. It is now - +- possible to refer to any "embedded" image or part - +- via a plain relative URL as you all know it. - +- - +------------------------------------------------------------------------------- + +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 tar.gz-structure. +The support class for the tar format is kdelibs/kio/ktar.*, written by Torben +and finished by David. + +The obvious benefits of this type of storage are: + - It's 100% non- proprietary as it uses only the already available formats + (XML, pictures, tar.gz, ...) and tools (tar, gzip). + - It enables anybody to edit the document directly; for instance, to update + an image (faster than launching the application), or to write scripts + that generate KOffice documents ! :) + - It is also easy to write an import filter for any other office-suite + application out there by reading the tar.gz file and extracting the XML out + of it (at the worst, the user can extract the XML file by himself, but then + the import loses embedded Parts and pictures). + +The tar.gz format also generates much smaller files than the old binary +store, since everything's gzipped. + +Name of the KOffice Files +------------------------- + +As some people suggested, using a "tgz"-ending is confusing; it's been dropped. +Instead, we use the "normal" endings like ".kwd", ".ksp", ".kpr", etc. To recognize +KOffice documents without a proper extension David Faure <faure@kde.org> +added some magic numbers to the gzip header (to see what I'm talking about +please use the "file" command on a KOffice document or see +http://lists.kde.org/?l=koffice-devel&m=98609092618214&w=2); + +External Structure +------------------ + +Here is a simple example to demonstrate the structure of a KOffice document. +Assume you have to write a lab-report. You surely will have some text, the +readings, some formulas and a few pictures (e.g. circuit diagram,...). +The main document will be a KWord-file. In this file you embed some KSpread- +tables, some KChart-diagramms, the KFormulas, and some picture-frames. You save +the document as "lab-report.kwd". Here is what the contents of the +tar.gz file will look like : + +lab-report.kwd: +--------------- +maindoc.xml -- The main XML file containing the KWord document. +documentinfo.xml -- Author and other "metadata" for KWord document. +pictures/ -- Pictures embedded in the main KWord document. +pictures/picture0.jpg +pictures/picture1.bmp +cliparts/ -- Cliparts embedded in the main KWord document. +cliparts/clipart0.wmf +part0/maindoc.xml -- for instance a KSpread embedded table. +part0/documentinfo.xml -- Author and other "metadata" for KSpread table. +part0/part1/maindoc.xml -- say a KChart diagram within the KSpread table. +part1/maindoc.xml -- say a KChart diagram. +part2/maindoc.xml -- why not a KIllustrator drawing. +part2/pictures/ -- Pictures embedded in the KIllustrator document. +part2/pictures/picture0.jpg +part2/pictures/picture1.bmp +part2/cliparts/ -- Cliparts embedded in the KIllustrator document. +part2/cliparts/clipart0.wmf +... + +Internal Name +------------- + +- Absolute references: + The API provided by this specification does not require application writers + or filter writers to know the details of the external structure: + + tar:/documentinfo.xml is saved as documentinfo.xml + tar:/0 is saved as part0/maindoc.xml + tar:/0/documentinfo.xml is saved as part0/documentinfo.xml + tar:/0/1 is saved as part0/part1/maindoc.xml + tar:/0/1/pictures/picture0.png + is saved as part0/part1/pictures/picture0.png + tar:/Table1/0 is saved as Table1/part0/maindoc.xml + + Note that this is the structure as of version 2.2 of this specification. + The only other format shipped with KDE2.0 is converted (on reading) to look + like this through the services of the "Internal Name". + + If the document does not contain any other Parts or pictures, then the + maindoc.xml and documentinfo.xml files are tarred and gzipped alone, + and saved with the proper extension (.kwd for KWord, .ksp for KSpread, + etc.). + The plan is to use relative paths everywhere, so please try not to use + absolute paths unless neccessary. + +- Relative references: + To allow parts to be self-contained, and to ease the work of filter + developers version 2.3 features relative links within the storage. + This means that the KoStore now has a "state" as in "there is something + like a current directory". You can specify a link like + "pictures/picture0.png" and depending on the current directory this will + be mapped to some absolute path. The surrounding code has to ensure that + the current path is maintained correctly, but due to that we can get rid + of the ugly prefix thingy. + + +Thank you for your attention, +Werner <trobin@kde.org> and David <faure@kde.org> +(edited by Chris Lee <lee@azsites.com> for grammer, spelling, and formatting) |