[tracker/sam/ontology-docs: 14/22] WIP: Rework the Ontology documentation



commit ff1866a6c7393b340211fd66473ab893a81fe377
Author: Sam Thursfield <sam afuera me uk>
Date:   Thu Apr 9 01:45:54 2020 +0200

    WIP: Rework the Ontology documentation
    
    This change was motivated by https://gitlab.gnome.org/GNOME/tracker/issues/104.
    We want to move to using URLs that we control for the ontologies, like
    this:
    
            http://api.gnome.org/ontologies/nfo/3.0/#Document
            http://api.gnome.org/ontologies/nfo/3.0/#url
    
    For this scheme to work, each ontology needs to document all classes
    and properties on a single page.
    
    It's an opportunity to reorganize the documentation too and try to
    prioritize the most important info.

 docs/reference/ontology/nmm-introduction.xml |  16 ++--
 docs/tools/ttl2xml.c                         |   2 -
 docs/tools/ttl_model.c                       |  17 ++++
 docs/tools/ttl_model.h                       |   2 +
 docs/tools/ttl_xml.c                         | 117 ++++++++++++++++----------
 docs/tools/ttlresource2xml.c                 | 120 ++++++++++++---------------
 docs/tools/ttlresource2xml.h                 |   5 +-
 7 files changed, 155 insertions(+), 124 deletions(-)
---
diff --git a/docs/reference/ontology/nmm-introduction.xml b/docs/reference/ontology/nmm-introduction.xml
index 51353ee24..a02994dac 100644
--- a/docs/reference/ontology/nmm-introduction.xml
+++ b/docs/reference/ontology/nmm-introduction.xml
@@ -1,6 +1,6 @@
-<section id="nmm-explanation">
+<refsection id="nmm-overview">
 <title>Overview</title>
-<sect2>
+<refsection>
 <title>Introduction</title>
 
 <para>This ontology extends NIE (Nepomuk Information Element ontology) and NFO (Nepomuk File Ontology) into 
the domains of multimedia, including Images, Videos, Music and Radio, and includes a couple of properties to 
support uPnP sharing.</para>
@@ -8,21 +8,21 @@
 <para>This ontology replaces/complements NID3 and NEXIF. Those ontologies are a direct map of the respective 
metadata standards, which makes very difficult to map cleanly other standards (like gstreamer metadata, mp4, 
ogg, and so on). Besides, those ontologies contain a lot of very low level technical information that is 
useless to the average user of the desktop.</para>
 
 <para>Our approach in NMM is to keep the minimum properties that make sense for the user, and are present in 
all (or almost all) specific metadata formats. A profesional photographer (or musician) who needs more 
fine-grained details for its documents, is free to add also nID3 information or other extensions to the 
ontology.</para>
-</sect2>
+</refsection>
 
-<sect2>
+<refsection>
   <title>Images domain</title>
 
 <para>The core of images in NMM ontology is the class <link linkend="nmm-Photo">nmm:Photo.</link> It is 
(through a long hierarchy) a <link linkend="nie-InformationElement">nie:InformationElement</link>, an 
interpretation of some bytes. It has properties to store the basic information (camera, metering mode, white 
balance, flash), and inherits from <link linkend="nfo-Image">nfo:Image</link> orientation (<link 
linkend="nfo-Image.nfo-orientation">nfo:orientation</link>) and resolution (<link 
linkend="nfo-Image.nfo-verticalResolution">nfo:verticalResolution</link> and <link 
linkend="nfo-Image.nfo-horizontalResolution">nfo:horizontalResolution</link>).</para>
 
 <para>Note that for tags, nie:keywords (from nie:InformationElement) can be used, or the <link 
linkend="nao-ontology">NAO</link> ontology.</para>
-</sect2>
+</refsection>
 
-<sect2>
+<refsection>
   <title>Radio domain</title>
 <para>NMM includes classes and properties to represent analog and digital radio stations. There is a class 
<link linkend="nmm-RadioStation">nmm:RadioStation</link> on the <link 
linkend="nie-InformationElement">nie:InformationElement</link> side of the ontology, representing what the 
user sees about that station (genre via PTY codes, icon, plus title inherited from 
nie:InformationElement)</para>
 <para>A <link linkend="nmm-RadioStation">nmm:RadioStation</link> can have one or more <link 
linkend="nmm-RadioStation.nmm-carrier">nmm:carrier</link> properties representing the different frequencies 
(or links when it is digitial) it can be tuned. This property links the station with <link 
linkend="nfo-MediaStream">nfo:MediaStream</link>, but usually it will point to one of the subclasses: <link 
linkend="nmm-DigitalRadio">nmm:DigitalRadio</link> (if digital) or <link 
linkend="nmm-AnalogRadio">nmm:AnalogRadio</link> (if analog). An analog station has properties as modulation 
and frequency, while the digial station has streaming bitrate, encoding or protocol.</para>
 <para>Note that nfo:MediaStream refers to a flux of bytes/data, and it is on the <link 
linkend="nie-DataObject">nie:DataObject</link> side of the ontology</para>
 
-</sect2>
-</section>
+</refsection>
+</refsection>
diff --git a/docs/tools/ttl2xml.c b/docs/tools/ttl2xml.c
index e22b4fef0..bc6ab3a1c 100644
--- a/docs/tools/ttl2xml.c
+++ b/docs/tools/ttl2xml.c
@@ -173,8 +173,6 @@ main (gint argc, gchar **argv)
        }
        g_list_free_full (description_files, (GDestroyNotify) g_object_unref);
 
-       generate_ontology_class_docs (ontology, output_file);
-
        ttl_loader_free_ontology (ontology);
        g_option_context_free (context);
 
diff --git a/docs/tools/ttl_model.c b/docs/tools/ttl_model.c
index cf45d5227..325492036 100644
--- a/docs/tools/ttl_model.c
+++ b/docs/tools/ttl_model.c
@@ -183,3 +183,20 @@ ttl_model_name_to_shortname (Ontology    *ontology,
 
        return g_strconcat (short_prefix, separator, suffix, NULL);
 }
+
+gchar *
+ttl_model_name_to_basename (Ontology    *ontology,
+                            const gchar *name)
+{
+       g_autofree gchar *prefix = NULL;
+       const gchar *suffix;
+
+       prefix = name_get_prefix (ontology, name);
+
+       if (!prefix)
+               return g_strdup (name);
+
+       suffix = &name[strlen (prefix)];
+
+       return g_strdup (suffix);
+}
diff --git a/docs/tools/ttl_model.h b/docs/tools/ttl_model.h
index 3a0be9871..5d189fdb4 100644
--- a/docs/tools/ttl_model.h
+++ b/docs/tools/ttl_model.h
@@ -84,6 +84,8 @@ gchar *               ttl_model_name_to_shortname (Ontology    *ontology,
                                                    const gchar *name,
                                                    const gchar *separator);
 
+gchar *               ttl_model_name_to_basename (Ontology    *ontology,
+                                                  const gchar *name);
 G_END_DECLS
 
 #endif /* __TRACKER_TTL_MODEL_H__ */
diff --git a/docs/tools/ttl_xml.c b/docs/tools/ttl_xml.c
index 44d10379c..4937bedbe 100644
--- a/docs/tools/ttl_xml.c
+++ b/docs/tools/ttl_xml.c
@@ -20,6 +20,7 @@
 #include <glib/gprintf.h>
 
 #include "ttl_xml.h"
+#include "ttlresource2xml.h"
 
 typedef struct {
        Ontology *ontology;
@@ -89,58 +90,76 @@ print_deprecated_message (FILE *f)
 static void
 print_xml_header (FILE *f, OntologyDescription *desc)
 {
-        gchar *upper_name;
-
-        g_fprintf (f, "<?xml version='1.0' encoding='UTF-8'?>\n");
+       g_fprintf (f, "<?xml version='1.0' encoding='UTF-8'?>\n");
        g_fprintf (f, "<!DOCTYPE book PUBLIC \"-//OASIS//DTD DocBook XML V4.5//EN\"\n"
-                  "        \"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd\"; [\n");
+                  "        \"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd\"; [\n");
        g_fprintf (f, "<!ENTITY %% local.common.attrib \"xmlns:xi  CDATA  #FIXED 
'http://www.w3.org/2003/XInclude'\">\n");
        g_fprintf (f, "]>");
 
-        g_fprintf (f, "<chapter id='%s-ontology' xmlns:xi=\"http://www.w3.org/2003/XInclude\";>\n", 
desc->localPrefix);
-
-        upper_name = g_ascii_strup (desc->localPrefix, -1);
-        g_fprintf (f, "<title>%s: %s</title>\n", desc->title, desc->description ? desc->description : "");
-        g_free (upper_name);
-
-        print_people_list (f, "Authors:", desc->authors);
-        print_people_list (f, "Editors:", desc->editors);
-        print_people_list (f, "Contributors:", desc->contributors);
-
-        print_link_as_varlistentry (f, "Upstream:", "Upstream version", desc->upstream);
-        print_link_as_varlistentry (f, "ChangeLog:", "Tracker changes", desc->gitlog);
-
-        if (desc->copyright) {
-               g_fprintf (f, "<varlistentry>\n");
-               g_fprintf (f, "  <term>Copyright:</term>\n");
-               g_fprintf (f, "  <listitem>\n");
-               g_fprintf (f, "<para>%s</para>\n", desc->copyright);
-               g_fprintf (f, "  </listitem>\n");
-               g_fprintf (f, "</varlistentry>\n");
-        }
+       g_fprintf (f, "<refentry id='%s' xmlns:xi=\"http://www.w3.org/2003/XInclude\";>\n", desc->localPrefix);
+       g_fprintf (f, "<refmeta>\n");
+       g_fprintf (f, "  <refentrytitle>%s</refentrytitle>\n", desc->title);
+       g_fprintf (f, "</refmeta>\n");
+       g_fprintf (f, "<refnamediv>\n");
+       g_fprintf (f, "<refname>%s</refname>", desc->title);
+       g_fprintf (f, "<refpurpose>%s</refpurpose>", desc->description);
+       g_fprintf (f, "</refnamediv>\n");
 }
 
 static void
-print_xml_footer (FILE *f)
+print_xml_footer (FILE *f, OntologyDescription *desc)
 {
-       g_fprintf (f,"</chapter>\n");
+       g_fprintf (f, "<refsect1>\n");
+       g_fprintf (f, "<title>Credits and Copyright</title>\n");
+       print_people_list (f, "Authors:", desc->authors);
+       print_people_list (f, "Editors:", desc->editors);
+       print_people_list (f, "Contributors:", desc->contributors);
+
+       print_link_as_varlistentry (f, "Upstream:", "Upstream version", desc->upstream);
+       print_link_as_varlistentry (f, "ChangeLog:", "Tracker changes", desc->gitlog);
+
+       if (desc->copyright) {
+               g_fprintf (f, "<varlistentry>\n");
+               g_fprintf (f, "  <term>Copyright:</term>\n");
+               g_fprintf (f, "  <listitem>\n");
+               g_fprintf (f, "<para>%s</para>\n", desc->copyright);
+               g_fprintf (f, "  </listitem>\n");
+               g_fprintf (f, "</varlistentry>\n");
+    }
+
+       g_fprintf (f, "</refsect1>\n");
+       g_fprintf (f, "</refentry>\n");
 }
 
 static void
-print_ontology_class (Ontology      *ontology,
-                     OntologyClass *def,
-                     FILE          *f)
+print_class_list (FILE       *f,
+                  Ontology   *ontology,
+                  const char *id,
+                  GList      *classes)
 {
-       gchar *name, *id;
-
-       g_return_if_fail (f != NULL);
-
-       name = ttl_model_name_to_shortname (ontology, def->classname, NULL);
-       id = ttl_model_name_to_shortname (ontology, def->classname, "-");
-       g_fprintf (f, "<xi:include href='%s.xml'/>\n", id);
-       g_free (id);
+       GList *l;
+
+       g_fprintf (f, "<refsect1 id=\"%s.classes\">", id);
+       g_fprintf (f, "<title>Classes</title>");
+
+       g_fprintf (f, "<simplelist>\n");
+       for (l = classes; l; l = l->next) {
+               OntologyClass *klass;
+               g_autofree char *basename = NULL, *id = NULL;
+
+               klass = l->data;
+               basename = ttl_model_name_to_basename (ontology, klass->classname);
+               id = ttl_model_name_to_shortname (ontology, klass->classname, "-");
+               g_fprintf (f, "<member>");
+               g_fprintf (f, "<link linkend=\"%s\">%s</link>", id, basename);
+               if (klass->description) {
+                       g_fprintf (f, ": %s", klass->description);
+               }
+               g_fprintf (f, "</member>\n");
+       }
+       g_fprintf (f, "</simplelist>\n");
 
-        g_free (name);
+       g_fprintf (f, "</refsect1>");
 }
 
 void
@@ -151,7 +170,7 @@ ttl_xml_print (OntologyDescription *description,
 {
        GHashTableIter iter;
        gchar *upper_name, *path, *introduction, *basename;
-       OntologyClass *def;
+       GList *classes, *l;
        FILE *f;
 
        path = g_file_get_path (file);
@@ -159,9 +178,13 @@ ttl_xml_print (OntologyDescription *description,
        g_assert (f != NULL);
        g_free (path);
 
-        upper_name = g_ascii_strup (description->localPrefix, -1);
+       upper_name = g_ascii_strup (description->localPrefix, -1);
+       classes = g_hash_table_get_values (ontology->classes);
+
        print_xml_header (f, description);
 
+       print_class_list (f, ontology, description->localPrefix, classes);
+
        basename = g_strdup_printf ("%s-introduction.xml", description->localPrefix);
        introduction = g_build_filename (description_dir, basename, NULL);
        g_free (basename);
@@ -171,16 +194,18 @@ ttl_xml_print (OntologyDescription *description,
                           introduction);
        }
 
-        g_fprintf (f, "<section id='%s-classes'>\n", description->localPrefix);
+    g_fprintf (f, "<refsect1 id='%s-classes'>\n", description->localPrefix);
        g_fprintf (f, "<title>%s Ontology Classes</title>\n", upper_name);
        g_hash_table_iter_init (&iter, ontology->classes);
 
-       while (g_hash_table_iter_next (&iter, NULL, (gpointer *) &def)) {
-               print_ontology_class (ontology, def, f);
+       for (l = classes; l; l = l->next) {
+               print_ontology_class (ontology, l->data, f);
        }
 
-        g_fprintf (f, "</section>\n");
-       print_xml_footer (f);
+    g_fprintf (f, "</refsect1>\n");
+       print_xml_footer (f, description);
+
+       g_list_free (classes);
 
        g_free (upper_name);
        g_free (introduction);
diff --git a/docs/tools/ttlresource2xml.c b/docs/tools/ttlresource2xml.c
index e5139583e..2d842653c 100644
--- a/docs/tools/ttlresource2xml.c
+++ b/docs/tools/ttlresource2xml.c
@@ -130,7 +130,7 @@ print_predefined_instances (FILE          *f,
        shortname = ttl_model_name_to_shortname (ontology, klass->classname, NULL);
        id = ttl_model_name_to_shortname (ontology, klass->classname, "-");
 
-       g_fprintf (f, "<refsect1 id='%s.predefined-instances'>", id);
+       g_fprintf (f, "<refsect3 id='%s.predefined-instances'>", id);
        g_fprintf (f, "<title>Predefined instances</title><para>");
        g_fprintf (f, "%s has the following predefined instances: ", shortname);
         g_fprintf (f, "<itemizedlist>\n");
@@ -147,7 +147,7 @@ print_predefined_instances (FILE          *f,
                g_free (shortname);
        }
 
-       g_fprintf (f, "</itemizedlist></para></refsect1>\n");
+       g_fprintf (f, "</itemizedlist></para></refsect3>\n");
 }
 
 static void
@@ -173,7 +173,7 @@ print_fts_properties (FILE          *f,
        shortname = ttl_model_name_to_shortname (ontology, klass->classname, NULL);
        id = ttl_model_name_to_shortname (ontology, klass->classname, "-");
 
-       g_fprintf (f, "<refsect1 id='%s.fts-properties'>", id);
+       g_fprintf (f, "<refsect3 id='%s.fts-properties'>", id);
        g_fprintf (f, "<title>Full-text-indexed properties</title><para>");
        g_fprintf (f, "%s has the following full-text-indexed properties: ", shortname);
         g_fprintf (f, "<itemizedlist>\n");
@@ -192,7 +192,7 @@ print_fts_properties (FILE          *f,
                g_free (prop_id);
        }
 
-       g_fprintf (f, "</itemizedlist></para></refsect1>\n");
+       g_fprintf (f, "</itemizedlist></para></refsect3>\n");
        g_free (shortname);
        g_free (id);
        g_list_free (fts_props);
@@ -512,6 +512,9 @@ class_get_parent_hierarchy_strings (OntologyClass *klass,
 
        context = hierarchy_context_new (klass, ontology);
 
+       /* Proceed from parent to child classes, populating the 
+        * context->strings array.
+        */
        for (c = context->hierarchy; c; c = c->next) {
                OntologyClass *cl = g_hash_table_lookup (ontology->classes, c->data);
                hierarchy_context_resolve_class (context, cl, ontology);
@@ -539,7 +542,7 @@ print_class_hierarchy (FILE          *f,
 
        id = ttl_model_name_to_shortname (ontology, klass->classname, "-");
 
-       g_fprintf (f, "<refsect1 id='%s.hierarchy'>", id);
+       g_fprintf (f, "<refsect3 id='%s.hierarchy'>", id);
        g_fprintf (f, "<title>Class hierarchy</title>");
        g_fprintf (f, "<screen>");
 
@@ -550,7 +553,7 @@ print_class_hierarchy (FILE          *f,
                g_fprintf (f, "    %s\n", str->str->str);
        }
 
-       g_fprintf (f, "</screen></refsect1>\n");
+       g_fprintf (f, "</screen></refsect3>\n");
        g_ptr_array_unref (strings);
 }
 
@@ -559,39 +562,53 @@ print_properties (FILE          *f,
                   OntologyClass *klass,
                   Ontology      *ontology)
 {
-       gchar *id, *prop_id, *shortname, *type_name, *type_class_id;
+       g_autofree gchar *id = NULL;
        GList *l;
 
        if (!klass->in_domain_of)
                return;
 
        id = ttl_model_name_to_shortname (ontology, klass->classname, "-");
-       g_fprintf (f, "<refsect1 id='%s.properties'>", id);
+       g_fprintf (f, "<refsect3 id='%s.properties'>", id);
        g_fprintf (f, "<title>Properties</title>");
 
+       g_fprintf (f, "<table>");
+       g_fprintf (f, "<thead><tr><td>Name</td><td>Type</td><td>Description</td></tr></thead>");
+
+       g_fprintf (f, "<tbody>");
        for (l = klass->in_domain_of; l; l = l->next) {
                OntologyProperty *prop;
+               g_autofree gchar *shortname = NULL, *basename = NULL, *type_name = NULL, *type_class_id = 
NULL, *prop_id = NULL;
 
                prop = g_hash_table_lookup (ontology->properties, l->data);
 
                prop_id = ttl_model_name_to_shortname (ontology, prop->propertyname, "-");
                shortname = ttl_model_name_to_shortname (ontology, prop->propertyname, NULL);
+               basename = ttl_model_name_to_basename (ontology, prop->propertyname);
                type_name = ttl_model_name_to_shortname (ontology, prop->range->data, NULL);
                type_class_id = ttl_model_name_to_shortname (ontology, prop->range->data, "-");
 
-               g_fprintf (f, "<refsect2 id='%s.%s' role='property'>", id, prop_id);
+               g_fprintf (f, "<tr>");
+
+               g_fprintf (f, "<td>");
                g_fprintf (f, "<indexterm zone='%s.%s'><primary sortas='%s'>%s</primary></indexterm>",
                           id, prop_id, shortname, shortname);
-               g_fprintf (f, "<title>The <literal>ā€œ%sā€</literal> property</title>", shortname);
-               g_fprintf (f, "<programlisting>ā€œ%sā€"
-                          "          <link linkend=\"%s\">%s</link>"
-                          "</programlisting>",
-                          shortname, type_class_id, type_name);
+               g_fprintf (f, "%s", basename);
+               g_fprintf (f, "</td>");
 
+               g_fprintf (f, "<td>");
+               g_fprintf (f, "<link linkend=\"%s\">%s</link>", type_class_id, type_name);
+               g_fprintf (f, "</td>");
+
+               g_fprintf (f, "<td>");
                if (prop->description) {
                        g_fprintf (f, "<para>%s</para>", prop->description);
                }
+               g_fprintf (f, "</td>");
+               g_fprintf (f, "</tr>");
 
+               /* FIXME: where to put this info? */
+               /*
                if (prop->max_cardinality) {
                        g_fprintf (f, "<para>Number of possible elements per resource (Cardinality): 
%s</para>",
                                   prop->max_cardinality);
@@ -648,68 +665,39 @@ print_properties (FILE          *f,
                        }
 
                        g_fprintf (f, "</itemizedlist></note>\n");
-               }
-
-               g_fprintf (f, "</refsect2>\n");
-
-               g_free (type_class_id);
-               g_free (type_name);
-               g_free (shortname);
-               g_free (prop_id);
+               }*/
        }
+       g_fprintf (f, "</tbody>");
+       g_fprintf (f, "</table>");
 
-       g_fprintf (f, "</refsect1>");
-       g_free (id);
-}
-
-static void
-generate_class_docs (OntologyClass *klass,
-                     Ontology      *ontology,
-                     FILE          *f)
-{
-       print_xml_header (f, klass, ontology);
-       print_class_hierarchy (f, klass, ontology);
-       print_predefined_instances (f, klass, ontology);
-       print_fts_properties (f, klass, ontology);
-       print_properties (f, klass, ontology);
-       print_xml_footer (f);
+       g_fprintf (f, "</refsect3>");
 }
 
 void
-generate_ontology_class_docs (Ontology *ontology,
-                              GFile    *output_dir)
+print_ontology_class (Ontology      *ontology,
+                      OntologyClass *klass,
+                      FILE          *f)
 {
-       OntologyClass *klass;
-       GList *classes, *l;
-       FILE *f;
-
-       classes = g_hash_table_get_values (ontology->classes);
-
-       for (l = classes; l; l = l->next) {
-               gchar *shortname, *class_filename, *output_file;
-               GFile *child;
-
-               klass = l->data;
-               shortname = ttl_model_name_to_shortname (ontology, klass->classname, "-");
-               class_filename = g_strdup_printf ("%s.xml", shortname);
-               child = g_file_get_child (output_dir, class_filename);
-
-               output_file = g_file_get_path (child);
-               g_object_unref (child);
+       g_autofree gchar *name, *id;
 
-               f = fopen (output_file, "w");
+       g_return_if_fail (f != NULL);
 
-               if (f == NULL) {
-                       g_error ("Could not open %s for writing.\n", output_file);
-               }
+       name = ttl_model_name_to_basename (ontology, klass->classname);
+       id = ttl_model_name_to_shortname (ontology, klass->classname, "-");
 
-               g_free (class_filename);
-               g_free (output_file);
-               g_free (shortname);
+       g_fprintf (f, "<refsect2 id='%s'>\n", id);
+       g_fprintf (f, "<title>%s</title>\n", name);
 
-               generate_class_docs (klass, ontology, f);
-               fclose (f);
+       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>\n");
 
-       g_list_free (classes);
+       print_class_hierarchy (f, klass, ontology);
+       print_predefined_instances (f, klass, ontology);
+       print_fts_properties (f, klass, ontology);
+       print_properties (f, klass, ontology);
+       g_fprintf (f, "</refsect2>\n");
 }
diff --git a/docs/tools/ttlresource2xml.h b/docs/tools/ttlresource2xml.h
index 546ca8b9b..a4d3c5f56 100644
--- a/docs/tools/ttlresource2xml.h
+++ b/docs/tools/ttlresource2xml.h
@@ -27,8 +27,9 @@
 
 G_BEGIN_DECLS
 
-void generate_ontology_class_docs (Ontology *ontology,
-                                   GFile    *output_dir);
+void print_ontology_class (Ontology      *ontology,
+                           OntologyClass *klass,
+                           FILE          *f);
 
 G_END_DECLS
 


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]