summaryrefslogtreecommitdiffstats
path: root/src/projects/kostore/SPEC
diff options
context:
space:
mode:
authortpearson <tpearson@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2010-02-03 02:15:56 +0000
committertpearson <tpearson@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2010-02-03 02:15:56 +0000
commit50b48aec6ddd451a6d1709c0942477b503457663 (patch)
treea9ece53ec06fd0a2819de7a2a6de997193566626 /src/projects/kostore/SPEC
downloadk3b-50b48aec6ddd451a6d1709c0942477b503457663.tar.gz
k3b-50b48aec6ddd451a6d1709c0942477b503457663.zip
Added abandoned KDE3 version of K3B
git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/applications/k3b@1084400 283d02a7-25f6-0310-bc7c-ecb5cbfe19da
Diffstat (limited to 'src/projects/kostore/SPEC')
-rw-r--r--src/projects/kostore/SPEC122
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)