[tracker] MLO: diagram and more explanations

[Ivan Frade <ifrade src gnome org>]

commit 2b5281e579e2d8e4495e89f56c5416b4a0f0d467
Author: Ivan Frade <ivan frade nokia com>
Date:   Fri Jan 29 00:37:51 2010 +0200

    MLO: diagram and more explanations

 docs/ontologies/mlo/explanation.xml       |   25 ++++++++++++++++++++-----
 docs/ontologies/mlo/location-overview.dia |  Bin 0 -> 3853 bytes
 docs/reference/ontology/Makefile.am       |    1 +
 docs/tools/Makefile.am                    |    1 +
 4 files changed, 22 insertions(+), 5 deletions(-)
---
diff --git a/docs/ontologies/mlo/explanation.xml b/docs/ontologies/mlo/explanation.xml
index adf24bb..7e419f8 100644
--- a/docs/ontologies/mlo/explanation.xml
+++ b/docs/ontologies/mlo/explanation.xml
@@ -9,7 +9,7 @@
 
 <section id="mlo-explanation">
  <title>Overview</title>
- <sect2 id="mlo-introduction">
+ <refsect2 id="mlo-introduction">
    <title>Introduction</title>
    
    <para>This is the proposed ontology to integrate geolocation information in the nepomuk set of ontologies. It defines a place in the space with the class <link linkend="mlo-GeoLocation">mlo:GeoLocation</link>. A place can be defined in different ways:</para>
@@ -31,14 +31,29 @@
      </listitem>
    </orderedlist>
    <para>These three representations are not exclusive, but is responsability of the applications to keep the data consistent.</para>
-   <para>Some places in the space has an special meaning, E.G. premises, buildings or services. This fact is represented in the ontology with the class <link linkend="mlo-Landmark">mlo:Landmark</link>. The title and description of the Landmark itself can be set using the <link linkend="nie-InformationElement">nie:InformationElement</link> properties (<link linkend="nie-title">nie:title</link>, <link linkend="nie-description">nie:description</link>, ...). A location is linked with a landmark with the property <link linkend="mlo-poiLocation">mlo:poiLocation</link> .</para>
+   <para>Some places in the space has an special meaning, E.G. premises, buildings or services. This fact is represented in the ontology with the class <link linkend="mlo-Landmark">mlo:Landmark</link>. The title and description of the Landmark itself can be set using the <link linkend="nie-InformationElement">nie:InformationElement</link> properties (<link linkend="nie-title">nie:title</link>, <link linkend="nie-description">nie:description</link>, ...). A location is linked with a landmark with the property <link linkend="mlo-location">mlo:location</link> inherited from the superclass Information Element.</para>
    <para>Landmark can be grouped in categories. For this reason, the ontology provides a property <link linkend="mlo-belongsToCategory">mlo:belongsToCategory</link> that links a Landmark with the class <link linkend="mlo-LandmarkCategory">mlo:LandmarkCategory</link> . The ontology includes also a predefined set of instances, very common an a de-facto standard in the industry.</para>
- </sect2>
+ </refsect2>
+
+ <refsect2 id="mlo-considerations">
+   <title>Considerations</title>
+
+   <para>A <link linkend="mlo-Landmark">mlo:Landmark</link> is linked with its location using the property <link linkend="mlo-location">mlo:location</link>, inherited from its superclass <link linkend="nie-InformationElement">nie:InformationElement</link>.</para>
 
- <refsect2 id="xxx-special-remarks">
-   <title>Special remarks</title>
+   <para>All classes in the ontology are subclasses of <link linkend="nie-InformationElement">nie:InformationElement</link>. It is not indicated in the graphic for the sake of clarity.</para>
+
+   <para>The three possible representations of a location (i.e. <link linkend="mlo-GeoPoint">mlo:GeoPoint</link>, <link linkend="mlo-GeoBoundingBox">mlo:GeoBoundingBox</link>, <link linkend="nco-PostalAddress">nco:PostalAddress</link>) are <emphasis>properties</emphasis> (and <emphasis>not subclasses</emphasis>) of the location object (instance of <link linkend="mlo-GeoLocation">mlo:GeoLocation</link>).</para>
+
+ </refsect2>
+
+ <refsect2 id="mlo-comments">
+   <title>Contract with applications</title>
 
    <para>We want to put special emphasis in the point that the applications must keep the different representations of the points consistent. Basically a point in the space is very unlikely to change (the point is there or not), but it is not difficult to assume that some application can complete the information, taking the postal addresses of the points without coordinates, and set the coordinates using some web service.</para>
+
+   <para>A box is considered as a <emphasis>2 dimensions</emphasis> area orientated to the north, aligned to parallels and meridians. The area is defined with two points: the southern east point (down left corner, in the <link linkend="mlo-bbSouthEast">mlo:bbSouthEast</link> property) and northern western point (upper right corner, in the <link linkend="mlo-bbNorthWest">mlo:bbNorthWest</link> property).</para>
+
+   <para><link linkend="mlo-LandmarkCategory">mlo:LandmarkCategory</link> has a property <link linkend="mlo-isRemovable">mlo:isRemovable</link> to mark is the category is predefined and shouldn't be deleted by the applications. Tracker (and probably other backends) doesn't enforce applications to respect this value, but consider it a gentleman agreement.</para>
  </refsect2>
 
 
diff --git a/docs/ontologies/mlo/location-overview.dia b/docs/ontologies/mlo/location-overview.dia
new file mode 100644
index 0000000..18af300
Binary files /dev/null and b/docs/ontologies/mlo/location-overview.dia differ
diff --git a/docs/reference/ontology/Makefile.am b/docs/reference/ontology/Makefile.am
index 417fc68..e9b2b77 100644
--- a/docs/reference/ontology/Makefile.am
+++ b/docs/reference/ontology/Makefile.am
@@ -39,6 +39,7 @@ ONTOLOGY_DIAGRAMS = 					\
 	feeds-overview.png				\
 	radio-overview.png				\
 	images-overview.png				\
+	location-overview.png				\
 	overview.png
 
 # Images to copy into HTML directory
diff --git a/docs/tools/Makefile.am b/docs/tools/Makefile.am
index cad0c93..32c59f4 100644
--- a/docs/tools/Makefile.am
+++ b/docs/tools/Makefile.am
@@ -60,6 +60,7 @@ ONTOLOGY_DIAGRAMS=							\
 	../ontologies/mfo/feeds-overview.png				\
 	../ontologies/nmm/radio-overview.png				\
 	../ontologies/nmm/images-overview.png				\
+	../ontologies/mlo/location-overview.png				\
 	../ontologies/nie/overview.png
 
 .dia.png: