Changes between Version 5 and Version 6 of SophieFormat

Timestamp:

11/07/09 18:06:00 (15 years ago)

Author:

mira

Comment:

--

SophieFormat

@@ -1 @@
-SOPHIE 2.0 RESOURCE FORMAT 
-The R3 format is used for persistence of a sophie 2.0 resources. It is simply the archive of the root directory of the resource. It contains: 
-•       _resource.xml file - xml description of all properties of the persisted resource 
-•       _data folder - incorporates all embedded files like images, videos, large texts, etc.
-•       _cache folder- containing all cached remote resources for offline usage 
-•       children directories – There is sub-directory for all child resources of the persisted one that have the same structure as the parent one. The names of those directories do not start with underscore and match the names of the child resources (not their titles!). 
-At the end of this page you can find a sample book. You can download it and open it with any file compression software (WinZip, WinRar, 7-zip, File Roller, etc) to gain a better understanding of the described structure. 
-Basically every resource could be persisted on its own so there are different file extensions for the different resources: ‘.page’, ‘.book’, ‘.frame’, etc. All of those are further extended by the generalized extension ‘.s2’. So if you were saving a page and you decided to name the file “Page A” the complete name of the file would be “Page A.page.s2”.
-The key part of every resource directory is its _resource.xml. It is different for the different kinds of resources but there are some common things: 
-* It begins with a standard <xml> tag.
- * The root tag is named ‘resource’. 
-  * It has a mandatory attribute ‘kind’ that specifies the kind of the persisted resource (book, page…).
-  * There is also mandatory attribute ‘format-version’ whose value is the id of the persistence format. For now this it is always "r3" but in future there could be different formats. )
- * There is a common child ‘title’. This is the name of the resource that is used in all user controls – the resource palette, links\timelines hud, bottom flap, etc. Its value is string: 
+SOPHIE 2.0 RESOURCE FORMAT [[BR]] [[BR]]
+The R3 format is used for persistence of a sophie 2.0 resources. It is simply the archive of the root directory of the resource. It contains: [[BR]] 
+•       _resource.xml file - xml description of all properties of the persisted resource [[BR]] [[BR]]
+•       _data folder - incorporates all embedded files like images, videos, large texts, etc. [[BR]] [[BR]]
+•       _cache folder- containing all cached remote resources for offline usage [[BR]] [[BR]]
+•       children directories – There is sub-directory for all child resources of the persisted one that have the same structure as the parent one. The names of those directories do not start with underscore and match the names of the child resources (not their titles!). [[BR]] [[BR]]
+At the end of this page you can find a sample book. You can download it and open it with any file compression software (WinZip, WinRar, 7-zip, File Roller, etc) to gain a better understanding of the described structure. [[BR]] [[BR]]
+Basically every resource could be persisted on its own so there are different file extensions for the different resources: ‘.page’, ‘.book’, ‘.frame’, etc. All of those are further extended by the generalized extension ‘.s2’. So if you were saving a page and you decided to name the file “Page A” the complete name of the file would be “Page A.page.s2”. [[BR]] [[BR]]
+The key part of every resource directory is its _resource.xml. It is different for the different kinds of resources but there are some common things: [[BR]] 
+* It begins with a standard <xml> tag. [[BR]] [[BR]]
+ * The root tag is named ‘resource’. [[BR]] [[BR]]
+  * It has a mandatory attribute ‘kind’ that specifies the kind of the persisted resource (book, page…).[[BR]] [[BR]]
+  * There is also mandatory attribute ‘format-version’ whose value is the id of the persistence format. For now this it is always "r3" but in future there could be different formats. ) [[BR]] [[BR]]
+ * There is a common child ‘title’. This is the name of the resource that is used in all user controls – the resource palette, links\timelines hud, bottom flap, etc. Its value is string: [[BR]] 
 {{{
 <title>
   Cool Book
 </title>
-}}}
- * There is a child ‘template’ that contains a reference to another resource. It is saved like this:
+}}}[[BR]] [[BR]]
+ * There could be a child ‘template’ that contains a reference to another resource. It is saved like this: [[BR]] 
 {{{
 <template>
   <ref location="../Resource Jd88Us"/>
 </template>
-}}} 
-This means that the referenced resource is located in the parent directory of the current one and is called “Resource Jd88Us”. Notice that this is the actual name of the resource, not its title. 
- * There is a ‘comment’ child that has a string value. 
- * There is an ‘import-origin’child that has a string value. It represents the URI of the import origin of this resource. 
-Those children nodes are common for all resources. They are not mandatory, though. So the ‘resource’ node could have some or all of them. When a property`s value is null there is no point in having empty tags for it. 
-There are many other children nodes that could be found in a _resource.xml depending on the kind of the persisted resource. Here we are presented most of them specifying where you could see them. Basically all properties of a resource are saved in this xml file in appropriate form depending on the type of the kept value. 
-When the persisted resource is a book its _resource.xml could have ‘page-size’ node that holds the size of the page- width and height: 
+}}} [[BR]] [[BR]]
+This means that the referenced resource is located in the parent directory of the current one and is called “Resource Jd88Us”. Notice that this is the actual name of the resource, not its title. [[BR]] 
+ * There could be a ‘comment’ child that has a string value. [[BR]] [[BR]]
+ * There could be an ‘import-origin’child that has a string value. It represents the URI of the import origin of this resource. [[BR]] [[BR]]
+Those children nodes are common for all resources. Most of them are not mandatory, though. So the ‘resource’ node could have some or all of them. When a property`s value is null there is no point in having empty tags for it. [[BR]] [[BR]]
+There are many other children nodes that could be found in a _resource.xml depending on the kind of the persisted resource. Here we are presented most of them specifying where you could see them. Basically all properties of a resource are saved in this xml file in appropriate form depending on the type of the kept value. [[BR]] [[BR]]
+When the persisted resource is a book its _resource.xml could have ‘page-size’ node that holds the size of the page- width and height:  [[BR]] 
 {{{
 <page-size>
@@ -35 +35 @@
   <width>640.0</width>
 </page-size>
-}}}
+}}} [[BR]] [[BR]]
  
-Book resources could also have 3 additional child nodes - ‘pages’, ‘page-templates’ and ‘frame-templates’. The value of these properties is a list of references to resources just like the template one. These child nodes have attribute ‘size’ that is integer number indicating how many elements this list holds. Each element of the list is persisted separately in a child node called accordingly ‘page’ or ‘template’. Those elements have attribute ‘index’ since the order of those elements is important to the way the book is presented. In xml files order of the children with the same name on the same level of the xml is not regarded. That way the list of pages for example page elements could change their place in the xml representation but we won`t lose the information for the order in which they were arranged in the book. 
+Book resources could also have 3 additional child nodes - ‘pages’, ‘page-templates’ and ‘frame-templates’. The value of these properties is a list of references to resources just like the template one. These child nodes have attribute ‘size’ that is integer number indicating how many elements this list holds. Each element of the list is persisted separately in a child node called accordingly ‘page’ or ‘template’. Those elements have attribute ‘index’ since the order of those elements is important to the way the book is presented. In xml files order of the children with the same name on the same level of the xml is not regarded. That way the list of pages for example page elements could change their place in the xml representation but we won`t lose the information for the order in which they were arranged in the book. [[BR]] [[BR]]
+Pages, groups and page extras (set of annotations on a page for example) could have ‘elements’ child node whose value is basically a list of references. There are a few differences, here the elements nodes are named ‘element’, the ref is persisted in ‘elementRef’ tag and there is an additional ‘entries’ child node that is used by the timelines. [[BR]] [[BR]]