[tracker/sam/ontology-docs: 24/25] docs/ontology: Link to upstream specs for core ontologies

[Sam Thursfield <sthursfield src gnome org>]

commit 214d41a88932cdc52f5144b2f8fc097c4a9fd141
Author: Sam Thursfield <sam afuera me uk>
Date:   Fri Apr 17 01:00:48 2020 +0200

    docs/ontology: Link to upstream specs for core ontologies
    
    Rather than duplicating documentation locally, we can now use the
    tracker:specification property to link to upstream specs.

 docs/tools/ttl_loader.c           | 17 +++++++++++++++
 docs/tools/ttl_model.c            |  4 ++++
 docs/tools/ttl_model.h            |  2 ++
 docs/tools/ttlresource2xml.c      | 15 +++++++++----
 src/ontologies/10-xsd.ontology    | 24 +++++++++++++++------
 src/ontologies/11-rdf.description |  1 -
 src/ontologies/11-rdf.ontology    | 45 ++++++++++++++++++++++++++++-----------
 7 files changed, 83 insertions(+), 25 deletions(-)
---
diff --git a/docs/tools/ttl_loader.c b/docs/tools/ttl_loader.c
index 54486bfe4..941cedbf1 100644
--- a/docs/tools/ttl_loader.c
+++ b/docs/tools/ttl_loader.c
@@ -39,6 +39,7 @@
 
 /* #define TRACKER_NAMESPACE "http://www.tracker-project.org/ontologies/tracker#Namespace"; */
 #define TRACKER_NS "http://www.tracker-project.org/ontologies/tracker#";
+#define TRACKER_SPECIFICATION TRACKER_NS "specification"
 #define TRACKER_NOTIFY TRACKER_NS "notify"
 #define TRACKER_FTS_INDEXED TRACKER_NS "fulltextIndexed"
 #define TRACKER_FTS_WEIGHT TRACKER_NS "weight"
@@ -183,6 +184,22 @@ load_in_memory (Ontology    *ontology,
                        }
                }
 
+       } else if (!g_strcmp0 (turtle_predicate, TRACKER_SPECIFICATION)) {
+               OntologyClass *klass;
+               OntologyProperty *prop;
+
+               klass = g_hash_table_lookup (ontology->classes, turtle_subject);
+               if (klass) {
+                       klass->specification = g_strdup (turtle_object);
+               } else {
+                       prop = g_hash_table_lookup (ontology->properties, turtle_subject);
+                       if (prop) {
+                               prop->specification = g_strdup (turtle_object);
+                       } else {
+                               g_error ("Error in specification (%s doesn't exist)", turtle_subject);
+                       }
+               }
+
        } else if (!g_strcmp0 (turtle_predicate, RDFS_DOMAIN)) {
                /*
                 * (prop A) has domain (class B)
diff --git a/docs/tools/ttl_model.c b/docs/tools/ttl_model.c
index 325492036..46801e164 100644
--- a/docs/tools/ttl_model.c
+++ b/docs/tools/ttl_model.c
@@ -28,6 +28,7 @@ ttl_model_class_new (const gchar *classname)
        def = g_new0 (OntologyClass, 1);
 
        def->classname = g_strdup (classname);
+       def->specification = NULL;
        def->superclasses = NULL;
        def->subclasses = NULL;
        def->in_domain_of = NULL;
@@ -51,6 +52,7 @@ ttl_model_class_free (OntologyClass *def)
        g_list_free_full (def->in_range_of, (GDestroyNotify) g_free);
 
        g_free (def->description);
+       g_free (def->specification);
 
        g_list_free_full (def->instances, (GDestroyNotify) g_free);
 
@@ -65,6 +67,7 @@ ttl_model_property_new (const gchar *propname)
        prop = g_new0 (OntologyProperty, 1);
 
        prop->propertyname = g_strdup (propname);
+       prop->specification = NULL;
        prop->type = NULL;
        prop->domain = NULL;
        prop->range = NULL;
@@ -93,6 +96,7 @@ ttl_model_property_free (OntologyProperty *def)
        g_free (def->max_cardinality);
        g_free (def->description);
        g_free (def->weight);
+       g_free (def->specification);
        g_free (def);
 }
 
diff --git a/docs/tools/ttl_model.h b/docs/tools/ttl_model.h
index 5d189fdb4..a3758b0a2 100644
--- a/docs/tools/ttl_model.h
+++ b/docs/tools/ttl_model.h
@@ -26,6 +26,7 @@ G_BEGIN_DECLS
 
 typedef struct {
        gchar *classname;
+       gchar *specification;
        GList *superclasses;
        GList *subclasses;
        GList *in_domain_of;
@@ -38,6 +39,7 @@ typedef struct {
 
 typedef struct {
        gchar *propertyname;
+       gchar *specification;
        GList *type;
        GList *domain;
        GList *range;
diff --git a/docs/tools/ttlresource2xml.c b/docs/tools/ttlresource2xml.c
index 7669174a8..ccf53a9ad 100644
--- a/docs/tools/ttlresource2xml.c
+++ b/docs/tools/ttlresource2xml.c
@@ -694,12 +694,19 @@ print_ontology_class (Ontology      *ontology,
        g_fprintf (f, "<refsect2 role='rdf-class' id='%s'>\n", id);
        g_fprintf (f, "<title>%s</title>\n", name);
 
-       g_fprintf (f, "<refsect3 id='%s.description'>\n", id);
-       g_fprintf (f, "  <title>Description</title>\n");
        if (klass->description) {
-               g_fprintf (f, "  <para>%s</para>", klass->description);
+               g_fprintf (f, "<refsect3 id='%s.description'>\n", id);
+               g_fprintf (f, "  <title>Description</title>\n");
+               g_fprintf (f, "  %s", klass->description);
+               g_fprintf (f, "</refsect3>\n");
+       }
+
+       if (klass->specification) {
+               g_fprintf (f, "<refsect3 id='%s.specification'>\n", id);
+               g_fprintf (f, "  <title>Specification</title>\n");
+               g_fprintf (f, "  <ulink url=\"%s\" />", klass->specification);
+               g_fprintf (f, "</refsect3>\n");
        }
-       g_fprintf (f, "</refsect3>\n");
 
        print_class_hierarchy (f, klass, ontology);
        print_predefined_instances (f, klass, ontology);
diff --git a/src/ontologies/10-xsd.ontology b/src/ontologies/10-xsd.ontology
index 879abda15..ccc912861 100644
--- a/src/ontologies/10-xsd.ontology
+++ b/src/ontologies/10-xsd.ontology
@@ -7,15 +7,25 @@ xsd: a tracker:Namespace, tracker:Ontology ;
        tracker:lastModified "2010-02-16T11:00:00Z" .
 
 xsd:string a rdfs:Class ;
-    rdfs:comment "The type of string properties." .
+       rdfs:comment "The type of string properties." ;
+       tracker:specification <https://www.w3.org/TR/xmlschema-2/#string> .
+
 xsd:boolean a rdfs:Class ;
-    rdfs:comment "The type of true / false properties." .
+       rdfs:comment "The type of true / false properties." ;
+       tracker:specification <https://www.w3.org/TR/xmlschema-2/#boolean> .
+
 xsd:integer a rdfs:Class ;
-    rdfs:comment "The type of integer properties." .
+       rdfs:comment "The type of integer properties." ;
+       tracker:specification <https://www.w3.org/TR/xmlschema-2/#integer> .
+
 xsd:double a rdfs:Class ;
-    rdfs:comment "The type of floating point properties." .
+       rdfs:comment "The type of floating point properties." ;
+       tracker:specification <https://www.w3.org/TR/xmlschema-2/#double> .
+
 xsd:date a rdfs:Class ;
-    rdfs:comment "The type of date properties." .
-xsd:dateTime a rdfs:Class ;
-    rdfs:comment "The type of date-time properties." .
+       rdfs:comment "The type of date properties." ;
+       tracker:specification <https://www.w3.org/TR/xmlschema-2/#date> .
 
+xsd:dateTime a rdfs:Class ;
+       rdfs:comment "The type of date-time properties." ;
+       tracker:specification <https://www.w3.org/TR/xmlschema-2/#dateTime> .
diff --git a/src/ontologies/11-rdf.description b/src/ontologies/11-rdf.description
index 2643af27f..4a7e961ee 100644
--- a/src/ontologies/11-rdf.description
+++ b/src/ontologies/11-rdf.description
@@ -8,5 +8,4 @@
        dsc:gitlog "http://git.gnome.org/cgit/tracker/log/src/ontologies/11-rdf.ontology";;
 
        dsc:localPrefix "rdf" ;
-       dsc:baseUrl "http://www.w3.org/2000/01/rdf-schema#"; ;
        dsc:relativePath "./11-rdf.ontology" .
diff --git a/src/ontologies/11-rdf.ontology b/src/ontologies/11-rdf.ontology
index e0815acbc..3572bd8f9 100644
--- a/src/ontologies/11-rdf.ontology
+++ b/src/ontologies/11-rdf.ontology
@@ -13,71 +13,84 @@ rdfs: a tracker:Namespace ;
 
 rdfs:Resource a rdfs:Class ;
        rdfs:label "All Resources" ;
-       rdfs:comment "All resources" .
+       rdfs:comment "All resources" ;
+       tracker:specification <https://www.w3.org/TR/rdf-schema/#ch_resource> .
 
 rdfs:Class a rdfs:Class ;
        rdfs:label "Class" ;
        rdfs:comment "The class of classes" ;
-       rdfs:subClassOf rdfs:Resource .
+       rdfs:subClassOf rdfs:Resource ;
+       tracker:specification <https://www.w3.org/TR/rdf-schema/#ch_class> .
 
 rdf:Property a rdfs:Class ;
        rdfs:label "Property" ;
        rdfs:comment "The class of RDF properties" ;
-       rdfs:subClassOf rdfs:Resource .
+       rdfs:subClassOf rdfs:Resource ;
+       tracker:specification <https://www.w3.org/TR/rdf-schema/#ch_property> .
 
 rdfs:Literal a rdfs:Class ;
        rdfs:label "Literal" ;
        rdfs:comment "The class of literal values, eg. textual strings and integers" ;
-       rdfs:subClassOf rdfs:Resource .
+       rdfs:subClassOf rdfs:Resource ;
+       tracker:specification <https://www.w3.org/TR/rdf-schema/#ch_literal> .
 
 rdfs:Datatype a rdfs:Class ;
        rdfs:label "Datatype" ;
        rdfs:comment "The class of RDF datatypes." ;
-       rdfs:subClassOf rdfs:Class .
+       rdfs:subClassOf rdfs:Class ;
+       tracker:specification <https://www.w3.org/TR/rdf-schema/#ch_datatype> .
 
 rdf:langString a rdfs:Class, rdfs:Datatype ;
        rdfs:subClassOf rdfs:Literal ;
        rdfs:label "langString" ;
-       rdfs:comment "The datatype of language-tagged string values" .
+       rdfs:comment "The datatype of language-tagged string values" ;
+       tracker:specification <https://www.w3.org/TR/rdf-schema/#ch_langstring> .
 
 rdf:type a rdf:Property ;
        rdfs:domain rdfs:Resource ;
        rdfs:comment "The subject is an instance of a class" ;
-       rdfs:range rdfs:Class .
+       rdfs:range rdfs:Class ;
+       tracker:specification <https://www.w3.org/TR/rdf-schema/#ch_type> .
 
 rdfs:subClassOf a rdf:Property ;
        rdfs:comment "The subject is a subclass of a class" ;
        rdfs:domain rdfs:Class ;
-       rdfs:range rdfs:Class .
+       rdfs:range rdfs:Class ;
+       tracker:specification <https://www.w3.org/TR/rdf-schema/#ch_subclassof> .
 
 rdfs:subPropertyOf a rdf:Property ;
        rdfs:comment "The subject is a subproperty of a property" ;
        rdfs:domain rdf:Property ;
-       rdfs:range rdf:Property .
+       rdfs:range rdf:Property ;
+       tracker:specification <https://www.w3.org/TR/rdf-schema/#ch_subpropertyof> .
 
 rdfs:comment a rdf:Property ;
        rdfs:comment "A description of the subject resource" ;
        nrl:maxCardinality 1 ;
        rdfs:domain rdfs:Resource ;
-       rdfs:range xsd:string .
+       rdfs:range xsd:string ;
+       tracker:specification <https://www.w3.org/TR/rdf-schema/#ch_comment> .
 
 rdfs:label a rdf:Property ;
        rdfs:comment "A human-readable name for the subject" ;
        nrl:maxCardinality 1 ;
        rdfs:domain rdfs:Resource ;
-       rdfs:range xsd:string .
+       rdfs:range xsd:string ;
+       tracker:specification <https://www.w3.org/TR/rdf-schema/#ch_label> .
 
 rdfs:domain a rdf:Property ;
        rdfs:comment "A domain of the subject property" ;
        nrl:maxCardinality 1 ;
        rdfs:domain rdf:Property ;
-       rdfs:range rdfs:Resource .
+       rdfs:range rdfs:Resource ;
+       tracker:specification <https://www.w3.org/TR/rdf-schema/#ch_domain> .
 
 rdfs:range a rdf:Property ;
        rdfs:comment "A range of the subject property" ;
        nrl:maxCardinality 1 ;
        rdfs:domain rdf:Property ;
-       rdfs:range rdfs:Class .
+       rdfs:range rdfs:Class ;
+       tracker:specification <https://www.w3.org/TR/rdf-schema/#ch_range> .
 
 rdf:List a rdfs:Class ;
        rdfs:label "List" ;
@@ -184,3 +197,9 @@ tracker:deprecated a rdf:Property;
        rdfs:range xsd:boolean;
        rdfs:label "deprecated";
        rdfs:comment "If this property is assigned, the subject class, property, or resource, is deprecated 
and should not be used in production systems any longer. It may be removed without further notice." .
+
+tracker:specification a rdf:Property ;
+       nrl:maxCardinality 1 ;
+       rdfs:domain rdfs:Class , rdfs:Property ;
+       rdfs:range xsd:string ;
+       rdfs:comment "Link to upstream specification for an ontology class or property." .