diff options
author | Carlos Garnacho <carlosg@gnome.org> | 2021-05-31 00:48:13 +0200 |
---|---|---|
committer | Carlos Garnacho <carlosg@gnome.org> | 2021-08-26 14:04:23 +0200 |
commit | 69f9fce133102a678a9894d2c1f1c242e8911ae2 (patch) | |
tree | 56c3221c85a5f697faaf86e36443b9193683d15e | |
parent | b4effff8a50562636b00bf71e18252edfaed725f (diff) | |
download | tracker-69f9fce133102a678a9894d2c1f1c242e8911ae2.tar.gz |
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.
-rw-r--r-- | docs/tools/meson.build | 1 | ||||
-rw-r--r-- | docs/tools/ttl_xml.c | 279 | ||||
-rw-r--r-- | docs/tools/ttlresource2xml.c | 308 | ||||
-rw-r--r-- | 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) diff --git a/docs/tools/ttlresource2xml.c b/docs/tools/ttlresource2xml.c deleted file mode 100644 index 84fef3cca..000000000 --- a/docs/tools/ttlresource2xml.c +++ /dev/null @@ -1,308 +0,0 @@ -/* - * Copyright (C) 2015, Carlos Garnacho - * - * This program is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License - * as published by the Free Software Foundation; either version 2 - * of the License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA - * 02110-1301, USA. - * - * Authors: Carlos Garnacho <carlosg@gnome.org> - */ - -#include <glib-object.h> -#include <glib/gprintf.h> -#include <gio/gio.h> -#include <stdlib.h> - -#include "tracker-ontology-model.h" -#include "tracker-utils.h" -#include "ttl_xml.h" -#include "ttlresource2xml.h" - -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; - gsize 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>"); -} - -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"); -} - -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); -} - diff --git a/docs/tools/ttlresource2xml.h b/docs/tools/ttlresource2xml.h deleted file mode 100644 index 80ba0bb4b..000000000 --- a/docs/tools/ttlresource2xml.h +++ /dev/null @@ -1,41 +0,0 @@ -/* - * Copyright (C) 2017, Red Hat, Inc - * - * This program is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License - * as published by the Free Software Foundation; either version 2 - * of the License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA - * 02110-1301, USA. - * - * Author: Carlos Garnacho <carlosg@gnome.org> - */ - -#ifndef __TTLRESOURCE2XML_H__ -#define __TTLRESOURCE2XML_H__ - -#include <glib.h> -#include "tracker-ontology-model.h" - -G_BEGIN_DECLS - -void print_ontology_class (TrackerOntologyModel *model, - TrackerOntologyClass *klass, - FILE *f); -void print_ontology_extra_properties (TrackerOntologyModel *model, - const char *ontology_prefix, - const char *classname, - GList *properties_for_class, - FILE *f); - -G_END_DECLS - -#endif /* __TTLRESOURCE2XML__ */ |