docs: Add information related to Flatpaksam/docs-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

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>
diff --git a/docs/reference/libtracker-sparql/private-store.xml b/docs/reference/libtracker-sparql/private-store.xml
deleted file mode 100644
index c598173ac..000000000
--- a/docs/reference/libtracker-sparql/private-store.xml
+++ /dev/null
@@ -1,113 +0,0 @@
-<?xml version='1.0' encoding="UTF-8"?>
-
-<part id="tracker-private-store" xmlns:xi="http://www.w3.org/2003/XInclude">
-  <title>Isolating tracker-store clients</title>
-  <partintro>
-    <para>
-      Every user of tracker_sparql_connection_get() or tracker_sparql_connection_get_async()
-      relies on an external tracker-store instance to maintain the database, and possibly
-      on additional tracker miners to write the data consumed by the application.
-    </para>
-    <para>
-      Traditionally there has been only a single instance of tracker-store and miners,
-      shared by all consumers of Tracker data. With Tracker 2.0 it became possible to let
-      clients spawn their own sets of these services.
-    </para>
-  </partintro>
-
-  <chapter id="private-daemons">
-    <title>Defining a private domain ontology</title>
-    <para>
-      In order to make Tracker aware of this private setup, a domain ontology rule
-      must be dropped by the application on $(datadir)/tracker/domain-ontologies/,
-      the file name will be usually the DBus name or application ID of the client
-      prepended by ".rule", eg. org.example.App.rule
-    </para>
-    <para>
-      The following example would allow org.example.App to set up a private set
-      of services to index the filesystem.
-    </para>
-    <programlisting>
-[DomainOntology]
-# All locations accept
-# 1) Paths relative from a variable, the variables
-#    may be: HOME, XDG_CACHE_HOME, XDG_DATA_HOME, XDG_RUNTIME_DIR,
-#    XDG_DESKTOP_DIR, XDG_DOCUMENTS_DIR, XDG_DOWNLOAD_DIR,
-#    XDG_MUSIC_DIR, XDG_PICTURES_DIR, XDG_PUBLICSHARE_DIR,
-#    XDG_VIDEOS_DIR.
-#
-#    eg. $XDG_CACHE_HOME/...
-#
-# 2) URIs
-#
-#    eg. file:///var/...
-#
-
-# Location for the Tracker database (not optional)
-CacheLocation=$XDG_CACHE_HOME/example-app
-
-# Location for the data journal, used in data recovery
-# situations (optional)
-JournalLocation=$XDG_DATA_HOME/example-app/journal
-
-# Name of the ontology to use, must be one located in
-# $(sharedir)/tracker/ontologies
-OntologyName=nepomuk
-
-# DBus name for the owner (not optional). Tracker will use
-# the domain as the prefix of the DBus name for all the
-# services related to this domain ontology.
-#
-# eg. org.gnome.Photos
-Domain=org.example.App
-
-# Miners that the domain ontology will require. This is
-# purely a hint (mainly for libtracker-control), and not
-# any sort of white list. Anything else knowing about this
-# domain ontology may still perform updates, miners and
-# non-miners.
-Miners=Miner.Files;Miner.Extract;
-    </programlisting>
-    <para>
-      The client could then instruct Tracker libraries to use
-      this private set up through the following call:
-    </para>
-    <programlisting>
-tracker_sparql_connection_set_domain ("org.example.App");
-    </programlisting>
-    <para>
-      It is also possible to pass a full path to the domain rule. If the first
-      character of the domain name is / it will be treated as a full path.
-    </para>
-  </chapter>
-  <chapter id="recommendations">
-    <title>Additional precautions and recommendations</title>
-    <para>
-      In order to work flawlessly with the created services, the
-      client must adopt some precautions that were optional in the
-      past, but now have become mandatory.
-    </para>
-    <formalpara>
-      <title>Use TrackerNotifier to receive notifications</title>
-      <para>
-	Listening directly to the GraphUpdated DBus signal will yield
-	the wrong results, since it relies on the DBus name adopted by
-	the default tracker-store service.
-      </para>
-    </formalpara>
-    <formalpara>
-      <title>Use TrackerMinerManager to ensure services are started</title>
-      <para>
-	The miner lifetime has been traditionally unclear, being those
-	usually deemed a system service that would usually be there.
-	When using private services that assumption can't hold true,
-	so the client is responsible for ensuring those services are
-	started.
-      </para>
-      <para>
-	Note that this is the recommended behavior anyway even if the
-	client were not to use private services.
-      </para>
-    </formalpara>
-  </chapter>
-</part>