diff options
| author | Christian Siefkes <christian@siefkes.net> | 2009-10-09 18:37:19 +0200 |
|---|---|---|
| committer | Christian Siefkes <christian@siefkes.net> | 2009-10-09 18:37:19 +0200 |
| commit | 9da7250ac27d992b50fc6021f3d46292e641ef13 (patch) | |
| tree | 34be1faf5c6bf03473b9068d58fb09576e2dceda | |
| parent | 51e740ac391fdc97135e3fa3195375f661fc030d (diff) | |
| download | tangiblebit-9da7250ac27d992b50fc6021f3d46292e641ef13.tar.gz tangiblebit-9da7250ac27d992b50fc6021f3d46292e641ef13.zip | |
More on package files
| -rw-r--r-- | doc/objects.html | 74 | ||||
| -rw-r--r-- | doc/objects.rst | 80 |
2 files changed, 135 insertions, 19 deletions
diff --git a/doc/objects.html b/doc/objects.html index d3f8cf9..8d712be 100644 --- a/doc/objects.html +++ b/doc/objects.html @@ -312,7 +312,10 @@ as follows:</p> </li> <li><p class="first"><em>name:</em> an informal name of the object</p> </li> -<li><p class="first"><em>URI:</em> a URI uniquely identifying the object</p> +<li><p class="first"><em>id:</em> a ID uniquely identifying the object; to ensure uniqueness, users +should use the inverse domain name convention (like Java packages) +starting with the inverse name of a domain they control (e.g. +<tt class="docutils literal"><span class="pre">com.example.coffeemaker</span></tt> if you own the example.com domain)</p> </li> <li><p class="first"><em>summary:</em> a short (one line) description of what the object is and what is can be used for</p> @@ -320,7 +323,7 @@ is can be used for</p> <li><p class="first"><em>description:</em> a longer description</p> </li> <li><p class="first"><em>thumbnail:</em> a list of small visual depictions of the object (pointers to -image file)</p> +image files)</p> </li> <li><p class="first"><em>authors:</em> list of the people which created/packaged the object</p> </li> @@ -417,8 +420,9 @@ any object would be pretty useless.</p> <h3>Metadata</h3> <ul class="simple"> <li><em>name:</em> an informal name and short summary of the process</li> -<li><em>URI:</em> a URI uniquely identifying the process. Tip: derive from the URI -of the corresponding object, TODO sample.</li> +<li><em>id:</em> a DI uniquely identifying the process. Tip: derive from the URI +of the corresponding object (e.g. +<tt class="docutils literal"><span class="pre">com.example.coffeemaker.buildit</span></tt> for the coffeemaker example above)</li> <li><em>description:</em> a description of the process</li> <li><em>authors:</em> list of the people which created/packaged the process (typically same as for the corresponding object)</li> @@ -441,8 +445,8 @@ determine language to use), e.g.:</p> object type ~ SheetMetal material = | - Aluminum - Steel + Aluminum + Steel width = 1.5 depth = 0.3 0.003 <= height <= 0.004 @@ -653,9 +657,61 @@ color blue <h2>Tangible Bit Object Description</h2> <p>The <em>Tangible Bit Object</em> file format (extension: <em>.tbob</em>) allows extracting objects with their relevant processes from the database and -sharing them computers and users.</p> -<p>TODO Design file format. Everything is packaged in a ZIP file, similar to -formats such as ODT and EPUB.</p> +sharing them computers and users. A TBOB file can contain one or many +objects with their relevant processes.</p> +<p>A TBOB package is a ZIP file (like formats such as ODT and EPUB).</p> +<p>First-level directories: the file contains one directory for objects and +one for each type of processes it contains:</p> +<pre class="literal-block"> +objects +build +setup +use +maintain +repair +replace +</pre> +<p>(Empty directories can be omitted.)</p> +<p>Second-level directories: Each object and each process is stored in a +subdirectory of the corresponding folder, using the object/process ID as +directory name (e.g. <tt class="docutils literal"><span class="pre">objects/com.example.coffeemaker</span></tt>).</p> +<p>Each object is represented by 3 simple plaintext (OGDL?) files:</p> +<ul class="simple"> +<li>properties.og: contains the object properties</li> +<li>processes.og: index of processes associated with the object</li> +<li>files.og: index of files associated with the object</li> +</ul> +<p>Each process is represented by 5 simple plaintext (OGDL?) files:</p> +<ul class="simple"> +<li>properties.og: contains the process metadata</li> +<li>dependencies.og: lists the input, tools, and constraints required</li> +<li>result.og: defines the output and the allowed parameter settings</li> +<li>operations.og: defines the list of operations to be performed</li> +<li>files.og: index of files associated with the process</li> +</ul> +<p>If an object or process contains files, they are stored in a third-level +folder named <tt class="docutils literal"><span class="pre">files</span></tt>.</p> +<p>TODO mimetype file?; internationalization/translated strings?</p> +<p>Sample directory structure:</p> +<pre class="literal-block"> +objects/ + com.example.coffeemaker/ + properties.og + processes.og + files.og + files/ + thumbnail.gif + frontview.jpg +build/ + com.example.coffeemaker.buildit/ + properties.og + dependencies.og + result.og + operations.og + files.og + files/ + blueprint.iges +</pre> <p>TODO Ensure that it's OK to package GPL'ed software with non-GPL'ed content in a single ZIP file (should be).</p> </div> diff --git a/doc/objects.rst b/doc/objects.rst index e68d9ca..d8ce71f 100644 --- a/doc/objects.rst +++ b/doc/objects.rst @@ -29,12 +29,15 @@ as follows: * *types:* non-empty list of types the object belongs to * *name:* an informal name of the object -* *URI:* a URI uniquely identifying the object +* *id:* a ID uniquely identifying the object; to ensure uniqueness, users + should use the inverse domain name convention (like Java packages) + starting with the inverse name of a domain they control (e.g. + ``com.example.coffeemaker`` if you own the example.com domain) * *summary:* a short (one line) description of what the object is and what is can be used for * *description:* a longer description * *thumbnail:* a list of small visual depictions of the object (pointers to - image file) + image files) * *authors:* list of the people which created/packaged the object * *maintainers:* list of people to contact regarding questions about the object @@ -130,8 +133,9 @@ Metadata ++++++++ * *name:* an informal name and short summary of the process -* *URI:* a URI uniquely identifying the process. Tip: derive from the URI - of the corresponding object, TODO sample. +* *id:* a DI uniquely identifying the process. Tip: derive from the URI + of the corresponding object (e.g. + ``com.example.coffeemaker.buildit`` for the coffeemaker example above) * *description:* a description of the process * *authors:* list of the people which created/packaged the process (typically same as for the corresponding object) @@ -156,8 +160,8 @@ determine language to use), e.g.:: object type ~ SheetMetal material = | - Aluminum - Steel + Aluminum + Steel width = 1.5 depth = 0.3 0.003 <= height <= 0.004 @@ -385,10 +389,66 @@ Tangible Bit Object Description The *Tangible Bit Object* file format (extension: *.tbob*) allows extracting objects with their relevant processes from the database and -sharing them computers and users. - -TODO Design file format. Everything is packaged in a ZIP file, similar to -formats such as ODT and EPUB. +sharing them computers and users. A TBOB file can contain one or many +objects with their relevant processes. + +A TBOB package is a ZIP file (like formats such as ODT and EPUB). + +First-level directories: the file contains one directory for objects and +one for each type of processes it contains:: + + objects + build + setup + use + maintain + repair + replace + +(Empty directories can be omitted.) + +Second-level directories: Each object and each process is stored in a +subdirectory of the corresponding folder, using the object/process ID as +directory name (e.g. ``objects/com.example.coffeemaker``). + +Each object is represented by 3 simple plaintext (OGDL?) files: + +- properties.og: contains the object properties +- processes.og: index of processes associated with the object +- files.og: index of files associated with the object + +Each process is represented by 5 simple plaintext (OGDL?) files: + +- properties.og: contains the process metadata +- dependencies.og: lists the input, tools, and constraints required +- result.og: defines the output and the allowed parameter settings +- operations.og: defines the list of operations to be performed +- files.og: index of files associated with the process + +If an object or process contains files, they are stored in a third-level +folder named ``files``. + +TODO mimetype file?; internationalization/translated strings? + +Sample directory structure:: + + objects/ + com.example.coffeemaker/ + properties.og + processes.og + files.og + files/ + thumbnail.gif + frontview.jpg + build/ + com.example.coffeemaker.buildit/ + properties.og + dependencies.og + result.og + operations.og + files.og + files/ + blueprint.iges TODO Ensure that it's OK to package GPL'ed software with non-GPL'ed content in a single ZIP file (should be). |