← Back to branch summary

~ubuntu-branches/ubuntu/precise/koffice/precise

« back to all changes in this revision

Viewing changes to libs/store/SPEC

  • Committer: Bazaar Package Importer
  • Author(s): Jonathan Riddell
  • Date: 2010-09-21 15:36:35 UTC
  • mfrom: (1.4.1 upstream) (60.2.11 maverick)
  • Revision ID: james.westby@ubuntu.com-20100921153635-6tejqkiro2u21ydi
Tags: 1:2.2.2-0ubuntu3
Add kubuntu_03_fix-crash-on-closing-sqlite-connection-2.2.2.diff and
kubuntu_04_support-large-memo-values-for-msaccess-2.2.2.diff as
recommended by upstream http://kexi-
project.org/wiki/wikiview/index.php@Kexi2.2_Patches.html#sqlite_stab
ility

Show diffs side-by-side

added added

removed removed

Lines of Context:
libs/store/SPEC
1
 
-------------------------------------------------------------------------------
2
 
-                                                                             -
3
 
-   KOffice Storage Format Specification - Version 2.3                        -
4
 
-                                                                             -
5
 
-   by Werner, last changed: 20020306 by Werner Trobin                        -
6
 
-                                                                             -
7
 
- History :                                                                   -
8
 
-  Version 1.0 : binary store                                                 -
9
 
-  Version 2.0 : tar.gz store                                                 -
10
 
-  Version 2.1 : cleaned up                                                   -
11
 
-  version 2.2 : shaheed    Put each part into its own directory to allow     -
12
 
-                           one filter to easily embed the results of another -
13
 
-                           and also to have its own documentinfo etc.        -
14
 
-                           Added description of naming convention.           -
15
 
-  Version 2.3 : werner     Allow the usage of relative links. It is now      -
16
 
-                           possible to refer to any "embedded" image or part -
17
 
-                           via a plain relative URL as you all know it.      -
18
 
-                                                                             -
19
 
-------------------------------------------------------------------------------
20
 
 
21
 
The purpose of this document is to define a common KOffice Storage Structure.
22
 
Torben, Reggie, and all the others agreed on storing embedded KOffice Parts
23
 
and binary data (e.g. pictures, movies, sounds) via a simple tar.gz-structure.
24
 
The support class for the tar format is kdelibs/kio/ktar.*, written by Torben
25
 
and finished by David.
26
 
 
27
 
The obvious benefits of this type of storage are:
28
 
 - It's 100% non- proprietary as it uses only the already available formats
29
 
   (XML, pictures, tar.gz, ...) and tools (tar, gzip).
30
 
 - It enables anybody to edit the document directly; for instance, to update
31
 
   an image (faster than launching the application), or to write scripts
32
 
   that generate KOffice documents ! :)
33
 
 - It is also easy to write an import filter for any other office-suite
34
 
   application out there by reading the tar.gz file and extracting the XML out
35
 
   of it (at the worst, the user can extract the XML file by himself, but then
36
 
   the import loses embedded Parts and pictures).
37
 
 
38
 
The tar.gz format also generates much smaller files than the old binary
39
 
store, since everything's gzipped.
40
 
 
41
 
Name of the KOffice Files
42
 
-------------------------
43
 
 
44
 
As some people suggested, using a "tgz"-ending is confusing; it's been dropped.
45
 
Instead, we use the "normal" endings like ".kwd", ".ksp", ".kpr", etc. To recognize
46
 
KOffice documents without a proper extension David Faure <faure@kde.org>
47
 
added some magic numbers to the gzip header (to see what I'm talking about
48
 
please use the "file" command on a KOffice document or see
49
 
http://lists.kde.org/?l=koffice-devel&m=98609092618214&w=2);
50
 
 
51
 
External Structure
52
 
------------------
53
 
 
54
 
Here is a simple example to demonstrate the structure of a KOffice document.
55
 
Assume you have to write a lab-report. You surely will have some text, the
56
 
readings, some formulas and a few pictures (e.g. circuit diagram,...).
57
 
The main document will be a KWord-file. In this file you embed some KSpread-
58
 
tables, some KChart-diagramms, the KFormulas, and some picture-frames. You save
59
 
the document as "lab-report.kwd". Here is what the contents of the
60
 
tar.gz file will look like :
61
 
 
62
 
lab-report.kwd:
63
 
---------------
64
 
maindoc.xml                 -- The main XML file containing the KWord document.
65
 
documentinfo.xml            -- Author and other "metadata" for KWord document.
66
 
pictures/                   -- Pictures embedded in the main KWord document.
67
 
pictures/picture0.jpg
68
 
pictures/picture1.bmp
69
 
cliparts/                   -- Cliparts embedded in the main KWord document.
70
 
cliparts/clipart0.wmf
71
 
part0/maindoc.xml           -- for instance a KSpread embedded table.
72
 
part0/documentinfo.xml      -- Author and other "metadata" for KSpread table.
73
 
part0/part1/maindoc.xml     -- say a KChart diagram within the KSpread table.
74
 
part1/maindoc.xml           -- say a KChart diagram.
75
 
part2/maindoc.xml           -- why not a KIllustrator drawing.
76
 
part2/pictures/             -- Pictures embedded in the KIllustrator document.
77
 
part2/pictures/picture0.jpg
78
 
part2/pictures/picture1.bmp
79
 
part2/cliparts/             -- Cliparts embedded in the KIllustrator document.
80
 
part2/cliparts/clipart0.wmf
81
 
...
82
 
 
83
 
Internal Name
84
 
-------------
85
 
 
86
 
- Absolute references:
87
 
    The API provided by this specification does not require application writers
88
 
    or filter writers to know the details of the external structure:
89
 
    
90
 
    tar:/documentinfo.xml   is saved as documentinfo.xml
91
 
    tar:/0                  is saved as part0/maindoc.xml
92
 
    tar:/0/documentinfo.xml is saved as part0/documentinfo.xml
93
 
    tar:/0/1                is saved as part0/part1/maindoc.xml
94
 
    tar:/0/1/pictures/picture0.png
95
 
                        is saved as part0/part1/pictures/picture0.png
96
 
    tar:/Table1/0           is saved as Table1/part0/maindoc.xml
97
 
    
98
 
    Note that this is the structure as of version 2.2 of this specification.
99
 
    The only other format shipped with KDE2.0 is converted (on reading) to look
100
 
    like this through the services of the "Internal Name".
101
 
    
102
 
    If the document does not contain any other Parts or pictures, then the
103
 
    maindoc.xml and documentinfo.xml files are tarred and gzipped alone,
104
 
    and saved with the proper extension (.kwd for KWord, .ksp for KSpread,
105
 
    etc.).
106
 
    The plan is to use relative paths everywhere, so please try not to use
107
 
    absolute paths unless neccessary.
108
 
 
109
 
- Relative references:
110
 
    To allow parts to be self-contained, and to ease the work of filter
111
 
    developers version 2.3 features relative links within the storage.
112
 
    This means that the KoStore now has a "state" as in "there is something
113
 
    like a current directory". You can specify a link like
114
 
    "pictures/picture0.png" and depending on the current directory this will
115
 
    be mapped to some absolute path. The surrounding code has to ensure that
116
 
    the current path is maintained correctly, but due to that we can get rid
117
 
    of the ugly prefix thingy.
118
 
 
119
 
 
120
 
Thank you for your attention,
121
 
Werner <trobin@kde.org> and David <faure@kde.org>
122
 
(edited by Chris Lee <lee@azsites.com> for grammar, spelling, and formatting)