[tracker/sam/ontology-docs: 13/25] WIP: Rework the Ontology documentation
- From: Sam Thursfield <sthursfield src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [tracker/sam/ontology-docs: 13/25] WIP: Rework the Ontology documentation
- Date: Fri, 17 Apr 2020 00:48:06 +0000 (UTC)
commit c6de148553b978bd1e9f02cbac0445295fa15732
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]
