[tracker/wip/carlosg/hotdoc: 20/47] docs: Move all XML generation into a single file

[Carlos Garnacho <carlosg src gnome org>]

commit 69f9fce133102a678a9894d2c1f1c242e8911ae2
Author: Carlos Garnacho <carlosg gnome org>
Date:   Mon May 31 00:48:13 2021 +0200

    docs: Move all XML generation into a single file
    
    We'll want to have multiple writers, so put all XML together in
    a single file.

 docs/tools/meson.build       |   1 -
 docs/tools/ttl_xml.c         | 279 ++++++++++++++++++++++++++++++++++++++-
 docs/tools/ttlresource2xml.c | 308 -------------------------------------------
 docs/tools/ttlresource2xml.h |  41 ------
 4 files changed, 278 insertions(+), 351 deletions(-)
---
diff --git a/docs/tools/meson.build b/docs/tools/meson.build
index 8eb2aeec7..c46cb732a 100644
--- a/docs/tools/meson.build
+++ b/docs/tools/meson.build
@@ -6,7 +6,6 @@ doctool_files = [
     'tracker-ontology-model.c',
     'tracker-utils.c',
     'ttl_xml.c',
-    'ttlresource2xml.c',
     'ttl2xml.c',
 ]
 
diff --git a/docs/tools/ttl_xml.c b/docs/tools/ttl_xml.c
index 375a8f7bb..87906c04d 100644
--- a/docs/tools/ttl_xml.c
+++ b/docs/tools/ttl_xml.c
@@ -18,9 +18,10 @@
  */
 
 #include <glib/gprintf.h>
+#include <gio/gio.h>
 
+#include "tracker-utils.h"
 #include "ttl_xml.h"
-#include "ttlresource2xml.h"
 
 typedef struct {
        TrackerOntologyModel *model;
@@ -28,6 +29,282 @@ typedef struct {
        FILE *output;
 } CallbackInfo;
 
+static void
+print_predefined_instances (FILE                 *f,
+                            TrackerOntologyClass *klass,
+                            TrackerOntologyModel *model)
+{
+       const gchar *id;
+       GList *l;
+
+       if (!klass->instances)
+               return;
+
+       id = klass->shortname;
+
+       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: ", klass->shortname);
+        g_fprintf (f, "<itemizedlist>\n");
+
+       for (l = klass->instances; l; l = l->next) {
+               g_fprintf (f, "<listitem><para>");
+               g_fprintf (f, "<literal>%s</literal>", (gchar*) l->data);
+               g_fprintf (f, "</para></listitem>\n");
+       }
+
+       g_fprintf (f, "</itemizedlist></para></refsect3>\n");
+}
+
+static void
+print_class_hierarchy (FILE                 *f,
+                       TrackerOntologyClass *klass,
+                       TrackerOntologyModel *model)
+{
+       GPtrArray *strings;
+       const gchar *id;
+       gint i;
+
+       strings = class_get_parent_hierarchy_strings (klass, model);
+
+       if (!strings)
+               return;
+
+       id = klass->shortname;
+
+       g_fprintf (f, "<refsect3 id='%s.hierarchy'>", id);
+       g_fprintf (f, "<title>Class hierarchy</title>");
+       g_fprintf (f, "<screen>");
+
+       for (i = 0; i < strings->len; i++) {
+               HierarchyString *str = g_ptr_array_index (strings, i);
+               g_fprintf (f, "    %s\n", str->str->str);
+       }
+
+       g_fprintf (f, "</screen></refsect3>\n");
+       g_ptr_array_unref (strings);
+}
+
+static void
+print_flag (FILE        *f,
+            const gchar *flag_property_link,
+            const gchar *icon_name,
+            const gchar *flag_description)
+{
+       /* This must not contain any linebreaks, or gtkdoc-fixxrefs will not
+        * resolve the link. See https://gitlab.gnome.org/GNOME/gtk-doc/-/issues/122
+        */
+       g_fprintf (f, "<link linkend=\"%s\">", flag_property_link);
+       g_fprintf (f, "<inlinemediaobject>");
+       g_fprintf (f, "<imageobject><imagedata fileref=\"%s\" /></imageobject>", icon_name);
+       g_fprintf (f, "<alt>%s</alt>", flag_description);
+       g_fprintf (f, "</inlinemediaobject>");
+       g_fprintf (f, "</link>");
+}
+
+static void
+print_property_table (FILE                 *f,
+                      TrackerOntologyModel *model,
+                      const char           *id,
+                      GList                *properties)
+{
+       GList *l, *m;
+       g_autoptr(GList) properties_sorted = NULL;
+
+       if (!properties)
+               return;
+
+       properties_sorted = g_list_sort (g_list_copy (properties), (GCompareFunc) strcmp);
+
+       /* We (ab)use the "struct_members" role to ensure devhelp2 <keyword> entries are
+        * generated by gtkdoc-mkhtml2. This is needed for xrefs to work between the
+        * libtracker-sparql and nepomuk ontology docs.
+        */
+       g_fprintf (f, "<refsect3 role=\"struct_members\" id=\"%s.properties\">", id);
+       g_fprintf (f, "<title>Properties</title>");
+
+       g_fprintf (f, "<informaltable frame=\"none\"><tgroup cols=\"4\">");
+       g_fprintf (f, 
"<thead><row><entry>Name</entry><entry>Type</entry><entry>Notes</entry><entry>Description</entry></row></thead>");
+
+       g_fprintf (f, "<tbody>");
+       for (l = properties_sorted; l; l = l->next) {
+               TrackerOntologyProperty *prop;
+               TrackerOntologyClass *range;
+               const gchar *shortname = NULL, *basename = NULL, *type_name = NULL, *type_class_id = NULL, 
*prop_id = NULL;
+
+               prop = tracker_ontology_model_get_property (model, l->data);
+               range = tracker_ontology_model_get_class (model, prop->range->data);
+
+               prop_id = shortname = prop->shortname;
+               basename = prop->basename;
+               type_name = range->basename;
+               type_class_id = range->shortname;
+
+               g_fprintf (f, "<row role=\"member\">");
+
+               /* Property name column */
+               g_fprintf (f, "<entry role=\"struct_member_name\">");
+               /* This id is globally unique and can be used for internal links.
+                * We abuse <structfield> so that gtkdoc-mkhtml2 creates a usable link. */
+               g_fprintf (f, "<para><structfield id=\"%s\">%s</structfield></para>", prop_id, basename);
+               /* This anchor is unique within the refentry and can be used for external links */
+               g_fprintf (f, "<anchor id='%s' />", basename);
+               g_fprintf (f, "<indexterm zone='%s'><primary sortas='%s'>%s</primary></indexterm>",
+                          prop_id, shortname, shortname);
+               g_fprintf (f, "</entry>");
+
+               /* Type column */
+               g_fprintf (f, "<entry>");
+               g_fprintf (f, "<link linkend=\"%s\">%s</link>", type_class_id, type_name);
+               g_fprintf (f, "</entry>");
+
+               /* Flags column */
+               g_fprintf (f, "<entry>");
+
+               if (prop->deprecated) {
+                       print_flag (f, "nrl-deprecated", "icon-deprecated.svg",
+                                   "This property is deprecated.");
+               }
+
+               if (prop->superproperties) {
+                       for (m = prop->superproperties; m; m = m->next) {
+                               const gchar *shortname = NULL, *superprop_id = NULL;
+                               g_autofree gchar *message = NULL;
+                               TrackerOntologyProperty *superprop;
+
+                               superprop = tracker_ontology_model_get_property (model, m->data);
+                               shortname = superprop_id = superprop->shortname;
+
+                               message = g_strdup_printf ("This property extends %s", shortname);
+
+                               print_flag (f, superprop_id, "icon-superproperty.svg", message);
+                       }
+               }
+
+               if (prop->max_cardinality != NULL && atoi (prop->max_cardinality) == 1) {
+                       /* Single valued properties are most common, so we don't display this. */
+               } else {
+                       g_autofree gchar *message = NULL;
+
+                       if (prop->max_cardinality != NULL && atoi (prop->max_cardinality) > 0) {
+                               message = g_strdup_printf ("This property can have a maximum of %i values", 
*prop->max_cardinality);
+                       } else {
+                               message = g_strdup_printf ("This property can have multiple values.");
+                       }
+                       print_flag (f, "nrl-maxCardinality", "icon-multivalue.svg", message);
+               }
+
+               if (prop->fulltextIndexed) {
+                       print_flag (f, "nrl-fulltextIndexed", "icon-fulltextindexed.svg",
+                                   "This property is full-text-indexed, and can be looked up through 
<literal>fts:match</literal>");
+               }
+
+               g_fprintf (f, "</entry>");
+
+               /* Description column */
+               g_fprintf (f, "<entry>");
+               if (prop->description) {
+                       g_fprintf (f, "<para>%s</para>", prop->description);
+               }
+               g_fprintf (f, "</entry>");
+               g_fprintf (f, "</row>");
+       }
+
+       g_fprintf (f, "</tbody></tgroup>");
+       g_fprintf (f, "</informaltable>");
+
+       g_fprintf (f, "</refsect3>");
+}
+
+static void
+print_ontology_class (TrackerOntologyModel *model,
+                      TrackerOntologyClass *klass,
+                      FILE                 *f)
+{
+       const gchar *name = NULL, *id = NULL;
+
+       g_return_if_fail (f != NULL);
+
+       name = klass->basename;
+       id = klass->shortname;
+
+       /* Anchor for external links. */
+       g_fprintf (f, "<anchor id='%s' />\n", name);
+
+       g_fprintf (f, "<refsect2 role='rdf-class' id='%s'>\n", id);
+       g_fprintf (f, "<title>%s</title>\n", name);
+
+       if (klass->description || klass->deprecated || klass->notify) {
+               g_fprintf (f, "<refsect3 id='%s.description'>\n", id);
+               g_fprintf (f, "  <title>Description</title>\n");
+
+               if (klass->description) {
+                       g_fprintf (f, "  %s", klass->description);
+               }
+
+               if (klass->deprecated) {
+                       g_fprintf (f, "<para>");
+                       print_flag (f, "nrl-deprecated", "icon-deprecated.svg", "Deprecated icon");
+                       g_fprintf (f, "This class is deprecated.");
+                       g_fprintf (f, "</para>");
+               }
+
+               if (klass->notify) {
+                       g_fprintf (f, "<para>");
+                       print_flag (f, "nrl-notify", "icon-notify.svg", "Notify icon");
+                       g_fprintf (f, "This class emits notifications about changes, and can "
+                                    "be monitored using <link 
linkend=\"TrackerNotifier\">TrackerNotifier</link>.");
+                       g_fprintf (f, "</para>");
+               }
+               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");
+       }
+
+       print_class_hierarchy (f, klass, model);
+       print_predefined_instances (f, klass, model);
+
+       print_property_table (f, model, id, klass->in_domain_of);
+
+       g_fprintf (f, "</refsect2>\n");
+}
+
+static void
+print_ontology_extra_properties (TrackerOntologyModel *model,
+                                 const char           *ontology_prefix,
+                                 const char           *classname,
+                                 GList                *properties_for_class,
+                                 FILE                 *f)
+{
+       TrackerOntologyClass *klass;
+       const gchar *short_classname = NULL, *class_id = NULL;
+       gchar *section_id = NULL;
+
+       g_return_if_fail (f != NULL);
+
+       klass = tracker_ontology_model_get_class (model, classname);
+       short_classname = class_id = klass->shortname;
+       section_id = g_strconcat (ontology_prefix, ".", class_id, NULL);
+
+       g_fprintf (f, "<refsect2 role='rdf-property-list' id='%s'>\n", section_id);
+       g_fprintf (f, "<title>Additional properties for %s</title>\n", short_classname);
+
+       g_fprintf (f, "<refsect3>\n");
+       g_fprintf (f, "  <title>Description</title>\n");
+       g_fprintf (f, "  <para>Properties this ontology defines which can describe %s resources.</para>",
+                  short_classname);
+       g_fprintf (f, "</refsect3>\n");
+
+       print_property_table (f, model, section_id, properties_for_class);
+       g_fprintf (f, "</refsect2>\n");
+
+       g_free (section_id);
+}
 
 static void
 print_itemized_list (FILE *f, GList *list)