[tracker/sam/ontology-docs: 25/25] WIP: docs: Add 'flags' column for ontology properties

[Sam Thursfield <sthursfield src gnome org>]

commit 03d1ef4e1f32186f9f2e735af0f17ca095b8ad6f
Author: Sam Thursfield <sam afuera me uk>
Date:   Fri Apr 17 02:46:25 2020 +0200

    WIP: docs: Add 'flags' column for ontology properties
    
    This relies on some tricky to get gtk-doc to correctly do
    cross-references...

 docs/reference/images/icon-fulltextindexed.svg |  1 +
 docs/reference/libtracker-sparql/meson.build   |  1 +
 docs/reference/meson.build                     |  4 ++
 docs/reference/ontology/meson.build            |  1 +
 docs/tools/ttl_xml.c                           |  6 +--
 docs/tools/ttlresource2xml.c                   | 62 ++++++++++++++++----------
 6 files changed, 49 insertions(+), 26 deletions(-)
---
diff --git a/docs/reference/images/icon-fulltextindexed.svg b/docs/reference/images/icon-fulltextindexed.svg
new file mode 100644
index 000000000..912fe3ff0
--- /dev/null
+++ b/docs/reference/images/icon-fulltextindexed.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg"; width="16" height="16"><g color="#000" font-weight="400" 
font-family="sans-serif" fill="#474747"><path d="M6.508 1C3.48 1 1.002 3.473 1.002 6.5c0 3.026 2.478 5.5 
5.506 5.5s5.504-2.474 5.504-5.5c0-3.027-2.476-5.5-5.504-5.5zm0 2a3.486 3.486 0 013.504 3.5c0 1.944-1.556 
3.5-3.504 3.5a3.488 3.488 0 01-3.506-3.5C3.002 4.555 4.56 3 6.508 3z" 
style="line-height:normal;font-variant-ligatures:normal;font-variant-position:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-alternates:normal;font-feature-settings:normal;text-indent:0;text-align:start;text-decoration-line:none;text-decoration-style:solid;text-decoration-color:#000;text-transform:none;text-orientation:mixed;shape-padding:0;isolation:auto;mix-blend-mode:normal;marker:none"
 overflow="visible"/><path d="M10 8.99a1 1 0 00-.695 1.717l4.004 4a1 1 0 101.414-1.414l-4.004-4A1 1 0 0010 
8.99z" style="line-height:normal;font-variant-ligatures:normal;font-variant-position:normal;fon
 
t-variant-caps:normal;font-variant-numeric:normal;font-variant-alternates:normal;font-feature-settings:normal;text-indent:0;text-align:start;text-decoration-line:none;text-decoration-style:solid;text-decoration-color:#000;text-transform:none;text-orientation:mixed;shape-padding:0;isolation:auto;mix-blend-mode:normal;marker:none"
 overflow="visible"/></g></svg>
\ No newline at end of file
diff --git a/docs/reference/libtracker-sparql/meson.build b/docs/reference/libtracker-sparql/meson.build
index 29181d8f0..f85a17bce 100644
--- a/docs/reference/libtracker-sparql/meson.build
+++ b/docs/reference/libtracker-sparql/meson.build
@@ -37,6 +37,7 @@ gnome.gtkdoc('libtracker-sparql',
     main_xml: 'libtracker-sparql-docs.xml',
     scan_args: ['--ignore-headers=' + ' '.join(private_headers)],
     content_files: ['overview.xml', 'examples.xml', 'ontologies.xml', 'private-store.xml', 
'migrating-1to2.xml', example_files],
+    html_assets: icon_images,
     gobject_typesfile: 'libtracker-sparql.types',
     dependencies: tracker_sparql_dep,
     fixxref_args: fixxref_args,
diff --git a/docs/reference/meson.build b/docs/reference/meson.build
index 882344b81..bcb829d02 100644
--- a/docs/reference/meson.build
+++ b/docs/reference/meson.build
@@ -11,6 +11,10 @@ fixxref_args = [
     '--extra-dir=@0@'.format(join_paths(docpath, 'libtracker-sparql')),
 ]
 
+icon_images = files(
+  'images/icon-fulltextindexed.svg'
+)
+
 subdir('libtracker-sparql')
 
 subdir('ontology')
diff --git a/docs/reference/ontology/meson.build b/docs/reference/ontology/meson.build
index acb353c24..8c750fadd 100644
--- a/docs/reference/ontology/meson.build
+++ b/docs/reference/ontology/meson.build
@@ -16,6 +16,7 @@ generated = custom_target('ontology-doc-generated',
 gnome.gtkdoc('ontology',
     src_dir: include_directories('.'),
     main_xml: 'ontology-docs.xml',
+    html_assets: icon_images,
     fixxref_args: fixxref_args,
     install_dir: 'tracker@0@-nepomuk'.format(tracker_api_major),
     install: true)
diff --git a/docs/tools/ttl_xml.c b/docs/tools/ttl_xml.c
index a32e377b2..b2aa935f5 100644
--- a/docs/tools/ttl_xml.c
+++ b/docs/tools/ttl_xml.c
@@ -240,17 +240,17 @@ print_toc_extra_properties (FILE       *f,
        while (g_hash_table_iter_next (&iter, (gpointer*) &classname, (gpointer*) &props_for_class)) {
                for (l = props_for_class; l; l = l->next) {
                        OntologyProperty *prop;
-                       g_autofree char *basename = NULL, *class_id = NULL;
+                       g_autofree char *basename = NULL, *prop_id = NULL;
 
                        prop = g_hash_table_lookup (ontology->properties, l->data);
 
                        basename = ttl_model_name_to_basename (ontology, prop->propertyname);
-                       class_id = ttl_model_name_to_shortname (ontology, classname, "-");
+                       prop_id = ttl_model_name_to_shortname (ontology, prop->propertyname, "-");
 
                        if (l != props_for_class) {
                                g_fprintf (f, ", ");
                        }
-                       g_fprintf (f, "<link linkend=\"%s.%s.property.%s\">%s</link>", id, class_id, 
basename, basename);
+                       g_fprintf (f, "<link linkend=\"%s\">%s</link>", prop_id, basename);
                }
        }
 
diff --git a/docs/tools/ttlresource2xml.c b/docs/tools/ttlresource2xml.c
index ccf53a9ad..9b36b109b 100644
--- a/docs/tools/ttlresource2xml.c
+++ b/docs/tools/ttlresource2xml.c
@@ -568,11 +568,15 @@ print_property_table (FILE          *f,
        if (!properties)
                return;
 
-       g_fprintf (f, "<refsect3 id='%s.properties'>", id);
+       /* 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, "<table>");
-       g_fprintf (f, "<thead><tr><td>Name</td><td>Type</td><td>Description</td></tr></thead>");
+       g_fprintf (f, "<informaltable frame=\"none\"><tgroup cols=\"4\">");
+       g_fprintf (f, 
"<thead><row><entry>Name</entry><entry>Type</entry><entry>Flags</entry><entry>Description</entry></row></thead>");
 
        g_fprintf (f, "<tbody>");
        for (l = properties; l; l = l->next) {
@@ -587,28 +591,44 @@ print_property_table (FILE          *f,
                type_name = ttl_model_name_to_basename (ontology, prop->range->data);
                type_class_id = ttl_model_name_to_shortname (ontology, prop->range->data, "-");
 
-               g_fprintf (f, "<tr>");
+               g_fprintf (f, "<row role=\"member\">");
 
-               g_fprintf (f, "<td>");
-               g_fprintf (f, "<indexterm zone='%s.%s'><primary sortas='%s'>%s</primary></indexterm>",
-                          id, prop_id, shortname, shortname);
-               /* This anchor is globally unique and can be used for internal links */
-               g_fprintf (f, "<anchor role='rdf-property' id='%s.property.%s' />", id, basename);
+               /* 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, "%s", basename);
-               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, "</entry>");
 
-               g_fprintf (f, "<td>");
+               /* Type column */
+               g_fprintf (f, "<entry>");
                g_fprintf (f, "<link linkend=\"%s\">%s</link>", type_class_id, type_name);
-               g_fprintf (f, "</td>");
+               g_fprintf (f, "</entry>");
+
+               /* Flags column */
+               g_fprintf (f, "<entry>");
+               if (prop->fulltextIndexed) {
+                       g_fprintf (f, "<link linkend=\"tracker-fulltextIndexed\">");
+                       g_fprintf (f, "  <inlinemediaobject>");
+                       g_fprintf (f, "    <imageobject><imagedata fileref=\"icon-fulltextindexed.svg\" 
/></imageobject>");
+                       g_fprintf (f, "    <alt>This property is full-text-indexed, and can be looked up 
through <literal>fts:match</literal></alt>");
+                       g_fprintf (f, "  </inlinemediaobject>");
+                       g_fprintf (f, "</link>");
+               }
+
+               g_fprintf (f, "</entry>");
 
-               g_fprintf (f, "<td>");
+               /* Description column */
+               g_fprintf (f, "<entry>");
                if (prop->description) {
                        g_fprintf (f, "<para>%s</para>", prop->description);
                }
-               g_fprintf (f, "</td>");
-               g_fprintf (f, "</tr>");
+               g_fprintf (f, "</entry>");
+               g_fprintf (f, "</row>");
 
                /* FIXME: where to put this info? */
                /*
@@ -619,10 +639,6 @@ print_property_table (FILE          *f,
                        g_fprintf (f, "<para>Number of possible elements per resource (Cardinality): 
Unlimited</para>");
                }
 
-               if (prop->fulltextIndexed) {
-                       g_fprintf (f, "<note><para>This property is full-text-indexed, and can be looked up 
through <literal>fts:match</literal>.</para></note>\n");
-               }
-
                if (prop->deprecated) {
                        g_fprintf (f, "<note><para>This property is deprecated.</para></note>\n");
                }
@@ -670,8 +686,8 @@ print_property_table (FILE          *f,
                        g_fprintf (f, "</itemizedlist></note>\n");
                }*/
        }
-       g_fprintf (f, "</tbody>");
-       g_fprintf (f, "</table>");
+       g_fprintf (f, "</tbody></tgroup>");
+       g_fprintf (f, "</informaltable>");
 
        g_fprintf (f, "</refsect3>");
 }
@@ -734,7 +750,7 @@ print_ontology_extra_properties (Ontology      *ontology,
        class_id = ttl_model_name_to_shortname (ontology, classname, "-");
        section_id = g_strconcat (ontology_prefix, ".", class_id, NULL);
 
-       g_fprintf (f, "<refsect2 id='%s'>\n", section_id);
+       g_fprintf (f, "<refsect2 role='rdf-property-list' id='%s'>\n", section_id);
        g_fprintf (f, "<title>Properties for %s</title>\n", short_classname);
 
        g_fprintf (f, "<refsect3>\n");