Warning, /multimedia/k3b/src/projects/kostore/SPEC.txt is written in an unsupported language. File is not indexed.
0001 ------------------------------------------------------------------------------- 0002 - - 0003 - KOffice Storage Format Specification - Version 2.3 - 0004 - - 0005 - by Werner, last changed: 20020306 by Werner Trobin - 0006 - - 0007 - History : - 0008 - Version 1.0 : binary store - 0009 - Version 2.0 : tar.gz store - 0010 - Version 2.1 : cleaned up - 0011 - version 2.2 : shaheed Put each part into its own directory to allow - 0012 - one filter to easily embed the results of another - 0013 - and also to have its own documentinfo etc. - 0014 - Added description of naming convention. - 0015 - Version 2.3 : werner Allow the usage of relative links. It is now - 0016 - possible to refer to any "embedded" image or part - 0017 - via a plain relative URL as you all know it. - 0018 - - 0019 ------------------------------------------------------------------------------- 0020 0021 The purpose of this document is to define a common KOffice Storage Structure. 0022 Torben, Reggie, and all the others agreed on storing embedded KOffice Parts 0023 and binary data (e.g. pictures, movies, sounds) via a simple tar.gz-structure. 0024 The support class for the tar format is kdelibs/kio/ktar.*, written by Torben 0025 and finished by David. 0026 0027 The obvious benefits of this type of storage are: 0028 - It's 100% non- proprietary as it uses only the already available formats 0029 (XML, pictures, tar.gz, ...) and tools (tar, gzip). 0030 - It enables anybody to edit the document directly; for instance, to update 0031 an image (faster than launching the application), or to write scripts 0032 that generate KOffice documents ! :) 0033 - It is also easy to write an import filter for any other office-suite 0034 application out there by reading the tar.gz file and extracting the XML out 0035 of it (at the worst, the user can extract the XML file by himself, but then 0036 the import loses embedded Parts and pictures). 0037 0038 The tar.gz format also generates much smaller files than the old binary 0039 store, since everything's gzipped. 0040 0041 Name of the KOffice Files 0042 ------------------------- 0043 0044 As some people suggested, using a "tgz"-ending is confusing; it's been dropped. 0045 Instead, we use the "normal" endings like ".kwd", ".ksp", ".kpr", etc. To recognize 0046 KOffice documents without a proper extension David Faure <faure@kde.org> 0047 added some magic numbers to the gzip header (to see what I'm talking about 0048 please use the "file" command on a KOffice document or see 0049 http://lists.kde.org/?l=koffice-devel&m=98609092618214&w=2); 0050 0051 External Structure 0052 ------------------ 0053 0054 Here is a simple example to demonstrate the structure of a KOffice document. 0055 Assume you have to write a lab-report. You surely will have some text, the 0056 readings, some formulas and a few pictures (e.g. circuit diagram,...). 0057 The main document will be a KWord-file. In this file you embed some KSpread- 0058 tables, some KChart-diagramms, the KFormulas, and some picture-frames. You save 0059 the document as "lab-report.kwd". Here is what the contents of the 0060 tar.gz file will look like : 0061 0062 lab-report.kwd: 0063 --------------- 0064 maindoc.xml -- The main XML file containing the KWord document. 0065 documentinfo.xml -- Author and other "metadata" for KWord document. 0066 pictures/ -- Pictures embedded in the main KWord document. 0067 pictures/picture0.jpg 0068 pictures/picture1.bmp 0069 cliparts/ -- Cliparts embedded in the main KWord document. 0070 cliparts/clipart0.wmf 0071 part0/maindoc.xml -- for instance a KSpread embedded table. 0072 part0/documentinfo.xml -- Author and other "metadata" for KSpread table. 0073 part0/part1/maindoc.xml -- say a KChart diagram within the KSpread table. 0074 part1/maindoc.xml -- say a KChart diagram. 0075 part2/maindoc.xml -- why not a KIllustrator drawing. 0076 part2/pictures/ -- Pictures embedded in the KIllustrator document. 0077 part2/pictures/picture0.jpg 0078 part2/pictures/picture1.bmp 0079 part2/cliparts/ -- Cliparts embedded in the KIllustrator document. 0080 part2/cliparts/clipart0.wmf 0081 ... 0082 0083 Internal Name 0084 ------------- 0085 0086 - Absolute references: 0087 The API provided by this specification does not require application writers 0088 or filter writers to know the details of the external structure: 0089 0090 tar:/documentinfo.xml is saved as documentinfo.xml 0091 tar:/0 is saved as part0/maindoc.xml 0092 tar:/0/documentinfo.xml is saved as part0/documentinfo.xml 0093 tar:/0/1 is saved as part0/part1/maindoc.xml 0094 tar:/0/1/pictures/picture0.png 0095 is saved as part0/part1/pictures/picture0.png 0096 tar:/Table1/0 is saved as Table1/part0/maindoc.xml 0097 0098 Note that this is the structure as of version 2.2 of this specification. 0099 The only other format shipped with KDE2.0 is converted (on reading) to look 0100 like this through the services of the "Internal Name". 0101 0102 If the document does not contain any other Parts or pictures, then the 0103 maindoc.xml and documentinfo.xml files are tarred and gzipped alone, 0104 and saved with the proper extension (.kwd for KWord, .ksp for KSpread, 0105 etc.). 0106 The plan is to use relative paths everywhere, so please try not to use 0107 absolute paths unless neccessary. 0108 0109 - Relative references: 0110 To allow parts to be self-contained, and to ease the work of filter 0111 developers version 2.3 features relative links within the storage. 0112 This means that the KoStore now has a "state" as in "there is something 0113 like a current directory". You can specify a link like 0114 "pictures/picture0.png" and depending on the current directory this will 0115 be mapped to some absolute path. The surrounding code has to ensure that 0116 the current path is maintained correctly, but due to that we can get rid 0117 of the ugly prefix thingy. 0118 0119 0120 Thank you for your attention, 0121 Werner <trobin@kde.org> and David <faure@kde.org> 0122 (edited by Chris Lee <lee@azsites.com> for grammer, spelling, and formatting)