[tracker] First documentation for NIE

[Ivan Frade <ifrade src gnome org>]

commit 7495b2ef78aeae480efc5ff52675bae24d594145
Author: Ivan Frade <ivan frade nokia com>
Date:   Tue Nov 17 00:08:46 2009 +0200

    First documentation for NIE

 data/ontologies/30-nie.ontology      |    9 ++++-
 docs/ontologies/nie/explanation.html |   73 +++++++++++++++++++++++++++++++++-
 2 files changed, 80 insertions(+), 2 deletions(-)
---
diff --git a/data/ontologies/30-nie.ontology b/data/ontologies/30-nie.ontology
index a7b493e..7a67058 100644
--- a/data/ontologies/30-nie.ontology
+++ b/data/ontologies/30-nie.ontology
@@ -11,14 +11,17 @@ nie: a tracker:Namespace ;
 
 nie:DataObject a rdfs:Class ;
 	rdfs:label "Data Object" ;
+	rdfs:comment "A unit of data that is created, annotated and processed on the user desktop. It represents a native structure the user works with. The usage of the term 'native'	is important. It means that a DataObject can be directly mapped to a data structure maintained by a native application.	This may be a file, a set of files or a part of a file. The granularity depends on the user. This class is not intended to be instantiated by itself. Use more specific subclasses." ;
 	rdfs:subClassOf rdfs:Resource .
 
 nie:DataSource a rdfs:Class ;
 	rdfs:label "Data Source" ;
+	rdfs:comment "A superclass for all entities from which DataObjects can be extracted. Each entity represents a native application or some other system that manages information that may be of interest to the user of the Semantic Desktop. Subclasses may include FileSystems, Mailboxes, Calendars, websites etc. The exact choice of subclasses and their properties is considered application-specific. Each data extraction application is supposed to provide it's own DataSource ontology. Such an ontology should contain supported data source types coupled with properties necessary for the application to gain access to the data sources. (paths, urls, passwords etc...)";
 	rdfs:subClassOf rdfs:Resource .
 
 nie:InformationElement a rdfs:Class ;
 	rdfs:label "Information Element" ;
+	rdfs:comment "A unit of content the user works with. This is a superclass for all interpretations of a DataObject." ;
 	rdfs:subClassOf rdfs:Resource .
 
 nie:title a rdf:Property ;
@@ -62,7 +65,7 @@ nie:language a rdf:Property ;
 
 nie:plainTextContent a rdf:Property ;
 	rdfs:label "Plain-text content" ;
-	rdfs:comment "Plain-text representation of the content" ;
+	rdfs:comment "Plain-text representation of the content of a InformationElement with all markup removed. The main purpose of this property is full-text indexing and search. Its exact content is considered application-specific. The user can make no assumptions about what is and what is not contained within. Applications should use more specific properties wherever possible.";
 	nrl:maxCardinality 1 ;
 	rdfs:domain nie:InformationElement ;
 	rdfs:range xsd:string ;
@@ -75,12 +78,14 @@ nie:informationElementDate a rdf:Property ;
 	rdfs:range xsd:dateTime .
 
 nie:legal a rdf:Property ;
+	rdfs:comment "A common superproperty for all properties that point at legal information about an Information Element";
 	rdfs:subPropertyOf dc:rights ;
 	nrl:maxCardinality 1 ;
 	rdfs:domain nie:InformationElement ;
 	rdfs:range xsd:string .
 
 nie:relatedTo a rdf:Property ;
+	rdfs:comment "A common superproperty for all relations between a piece of content and other pieces of data (which may be interpreted as other pieces of content).";
 	rdfs:subPropertyOf dc:relation ;
 	rdfs:domain nie:InformationElement ;
 	rdfs:range nie:DataObject .
@@ -119,6 +124,7 @@ nie:depends a rdf:Property ;
 
 nie:links a rdf:Property ;
 	rdfs:subPropertyOf nie:relatedTo ;
+	rdfs:comment "A linking relation. A piece of content links/mentions a piece of data";
 	nrl:maxCardinality 1 ;
 	rdfs:domain nie:InformationElement ;
 	rdfs:range nie:DataObject .
@@ -178,6 +184,7 @@ nie:lastRefreshed a rdf:Property ;
 
 # Bug in nepomuk specification. Taking domain from superproperty
 nie:license a rdf:Property ;
+        rdfs:comment "Terms and intellectual property rights licensing conditions.";
 	rdfs:subPropertyOf dc:rights , nie:legal ;
 	nrl:maxCardinality 1 ;
 	rdfs:domain nie:InformationElement ;
diff --git a/docs/ontologies/nie/explanation.html b/docs/ontologies/nie/explanation.html
index 8814262..d944d51 100644
--- a/docs/ontologies/nie/explanation.html
+++ b/docs/ontologies/nie/explanation.html
@@ -1,7 +1,78 @@
 <h2>Overview</h2>
 
-<h2>Special remarks</h2>
+<p>The core of the NEPOMUK Information Element Ontology and the entire
+  Ontology Framework revolves around the concepts of <a href="#DataObject">DataObject</a> and 
+ <a href="#InformationElement">InformationElement</a>. They express  the representation 
+ and content of a piece of data. Their specialized subclasses (defined
+ in the other ontologies) can be used to classify
+ a wide array of desktop resources and express them in RDF. 
+</p>
+
+<p>
+ <a href="#DataObject">DataObject</a> class represents a bunch of
+ bytes somwhere (local or remote), the physical entity that contain
+ data. The <emph>meaning</emph> (intepretation) of that entity, the
+ information for the user contained in those bytes (e.g. a music file,
+ a picture) is represented on the  
+<a href="#InformationElement">InformationElement</a> side of the
+ontology. 
+</p>
+
+<p>
+Both sides are linked using the
+property <a href="#interpretedAs">interpretedAs</a> (and its reverse
+<a href="#isStoredAs">isStoredAs</a>), indicating the correspondence
+between the physical element and its interpretation. There is also a
+property to
+link <a href="#InformationElement">InformationElement</a>s,
+representing the logical containment between them (like a picture and
+its album). 
+</p>
+
+<h3>Common properties</h3>
+<p>
+Given that the classes defined in this ontology are the superclasses for almost
+everything in the Nepomuk set of ontologies, the
+properties defined here will be inherited for a lot of classes. It is
+worth to comment few of them with special relevance:
+</p>
+<dl>
+  <dt><a href="#title">title</a><dt>
+  <dd>Title or name or short text describing the item</dd>
+  <dt><a href="#description">description</a><dt>
+  <dd>More verbose comment about the element</dd>
+  <dt><a href="#language">language</a><dt>
+  <dd>To specify the language of the item.</dd>
+  <dt><a href="#plainTextContent">plainTextContent</a><dt>
+  <dd>Just the raw content of the file, if it makes sense as text.</dd>
+  <dt><a href="#generator">generator</a><dt>
+  <dd>Software/Agent that set/produced the information.</dd>
+  <dt><a href="#usageCounter">usageCounter</a><dt>
+  <dd>Count number of accesses to the information. It can be an
+  indicator of relevance for advanced searches</dd>
+</dl>
+
+
+<h3>Dates and timestamps representations</h3>
+FIXME Explain the mess with dates
+<dl>
+  <dt><a href="#contentLastModified">contentLastModified</a><dt>
+  <dd>.</dd>
+  <dt><a href="#informationElementDate">informationElementDate</a><dt>
+  <dd>.</dd>
+  <dt><a href="#contentCreated">contentCreated</a><dt>
+  <dd>.</dd>
+  <dt><a href="#contentAccessed">contentAccessed</a><dt>
+  <dd>.</dd>
+  <dt><a href="#lastRefreshed">lastRefreshed</a><dt>
+  <dd>.</dd>
+</dl>
+
 
 <h2>Related information</h2>
 
+This explanation is just a brief extract from the
+original <a href="http://www.semanticdesktop.org/ontologies/nie";>
+Nepomuk NIE Ontology</a> web page.
+
 <h2>Graphical overview</h2>