[tracker/sam/docs-flatpak] docs: Add information related to Flatpak

[Sam Thursfield <sthursfield src gnome org>]

commit c32f172f1b48f6cfe9845ca233f643bde81abd0c
Author: Sam Thursfield <sam afuera me uk>
Date:   Tue Oct 13 13:51:09 2020 +0200

    docs: Add information related to Flatpak
    
    Also some general cleanups, in particular removing domain-ontology
    feature which now belongs in tracker-miners.git, and can be
    documented there with an example app.
    
    See: https://gitlab.gnome.org/GNOME/tracker/-/issues/236

 .../libtracker-sparql/libtracker-sparql-docs.xml   |   1 -
 docs/reference/libtracker-sparql/overview.xml      |  60 +++++++++--
 docs/reference/libtracker-sparql/private-store.xml | 113 ---------------------
 3 files changed, 53 insertions(+), 121 deletions(-)
---
diff --git a/docs/reference/libtracker-sparql/libtracker-sparql-docs.xml 
b/docs/reference/libtracker-sparql/libtracker-sparql-docs.xml
index 4b5793f77..792f309e7 100644
--- a/docs/reference/libtracker-sparql/libtracker-sparql-docs.xml
+++ b/docs/reference/libtracker-sparql/libtracker-sparql-docs.xml
@@ -50,7 +50,6 @@
   </part>
 
   <xi:include href="ontologies.xml"/>
-  <xi:include href="private-store.xml"/>
   <xi:include href="examples.xml"/>
   <xi:include href="limits.xml"/>
   <xi:include href="performance.xml"/>
diff --git a/docs/reference/libtracker-sparql/overview.xml b/docs/reference/libtracker-sparql/overview.xml
index 0e746e1a1..49587360f 100644
--- a/docs/reference/libtracker-sparql/overview.xml
+++ b/docs/reference/libtracker-sparql/overview.xml
@@ -4,13 +4,17 @@
   <title>Overview</title>
   <partintro>
     <para>
-      The libtracker-sparql library allows creating and connecting to
-      one or more "triplestore" databases.
+      Tracker SPARQL allows creating and connecting to one or more triplestore databases.
+      It is used by the
+      <ulink role="online-location" url="https://gitlab.gnome.org/GNOME/tracker-miners/";>
+        Tracker Miners filesystem indexer
+      </ulink>, and can also store and publish any kind of app data.
     </para>
     <para>
-      Data queries and updates are done using the SPARQL graph query
-      language. The <type><link linkend="TrackerResource">TrackerResource</link></type>
-      API provides helpers for updating data.
+      Querying data is done using the SPARQL graph query language. See the
+      <link linkend="Examples">Examples</link> to find out how this works.
+      Storing data can also be done using SPARQL, or using the
+      <type><link linkend="TrackerResource">TrackerResource</link></type> API.
     </para>
     <para>
       You can share a database over D-Bus using the
@@ -20,24 +24,66 @@
       query, or by connecting directly with
       <function><link 
linkend="tracker-sparql-connection-bus-new">tracker_sparql_connection_bus_new</link></function>.
     </para>
+    <para>
+      Tracker SPARQL partitions the database into multiple graphs.
+      You can implementing access control restrictions based on
+      graphs, and we provide a Flatpak portal that does so.
+      The number of graphs is <link linkend="limits">limited</link>.
+    </para>
   </partintro>
 
-
   <chapter id="tracker-overview-connection-methods">
     <title>Connection methods</title>
 
     <para>
         You can create and access a private store using
         <function><link 
linkend="tracker-sparql-connection-new">tracker_sparql_connection_new</link></function>.
+        This is useful to store app-specific data.
     </para>
     <para>
         To connect to another database on the same local machine, such as the
-        one exposed by the Tracker filesystem miner, use
+        one exposed by Tracker Miner FS, use
         <function><link 
linkend="tracker-sparql-connection-bus-new">tracker_sparql_connection_bus_new</link></function>.
     </para>
     <para>
         To connect to another a database on a remote machine, use
         <function><link 
linkend="tracker-sparql-connection-remote-new">tracker_sparql_connection_remote_new</link></function>.
+        This can be used to query online databases that provide a SPARQL
+        endpoint, such as
+        <ulink role="online-location" url="https://wiki.dbpedia.org/about";>DBpedia</ulink>
+        .
+    </para>
+  </chapter>
+
+  <chapter id="tracker-overview-flatpak">
+    <title>Connecting from Flatpak</title>
+
+    <para>
+        Tracker SPARQL provides a portal for the
+        <ulink role="online-location" url="https://flatpak.org/";>Flatpak</ulink>
+        application sandboxing system. This lets
+        you control which parts of a database each app can query.
+    </para>
+    <para>
+        The app's Flatpak manifest needs to specify which graph(s) the app will
+        access. See the <ulink role="online-location" 
url="https://gitlab.gnome.org/GNOME/tracker/-/blob/master/examples/flatpak/org.example.TrackerSandbox.json";>example
 app</ulink>
+        and the <ulink role="online-location" 
url="https://gnome.pages.gitlab.gnome.org/tracker/docs/commandline/#tracker-xdg-portal-3";>portal 
documentation</ulink>
+        to see how.
+        No code changes are needed in the app, as
+        <function><link 
linkend="tracker-sparql-connection-bus-new">tracker_sparql_connection_bus_new</link></function>.
+        will automatically try connect via the portal
+        if it can't talk to the given D-Bus name directly.
+    </para>
+    <para>
+        Tracker SPARQL is included in the <ulink role="online-location" 
url="https://docs.flatpak.org/en/latest/available-runtimes.html#gnome";>GNOME Flatpak SDK and runtime</ulink>.
+        If the app uses a different runtime, you may need to build Tracker SPARQL in the app manifest.
+    </para>
+    <para>
+        The app might use the Tracker Miner FS search index. Ideally this is done via the portal,
+        using the search index maintained on the host. Since not all OSes ship tracker-miner-fs-3,
+        we recommend that apps bundle it inside the Flatpak and connect to the bundled version as
+        a fallback. See <ulink role="online-location" 
url="https://gitlab.gnome.org/GNOME/gnome-music/";>GNOME Music</ulink>
+        for an example of how to do this.
     </para>
   </chapter>
 </part>