docs: Port "examples" to markdown

3 files changed, 99 insertions, 138 deletions

diff --git a/docs/reference/libtracker-sparql/examples.md b/docs/reference/libtracker-sparql/examples.md
new file mode 100644
index 000000000..e3340a4d9
--- /dev/null
+++ b/docs/reference/libtracker-sparql/examples.md
@@ -0,0 +1,98 @@
+Title: Examples
+
+This chapters shows some real examples of usage of the Tracker
+SPARQL Library.
+
+## Querying the Store
+
+First, a [class@Tracker.SparqlConnection] object must be acquired
+with [ctor@Tracker.SparqlConnection.new], [ctor@Tracker.SparqlConnection.bus_new]
+or [ctor@Tracker.SparqlConnection.remote_new].
+
+Then, a query can be launched either synchronously ([method@Tracker.SparqlConnection.query])
+or asynchronously ([method@Tracker.SparqlConnection.query_async]). If launched
+asynchronously, the results of the query can be obtained with
+[method@Tracker.SparqlConnection.query_finish].
+
+If the query was successful, a [class@Tracker.SparqlCursor]
+will be available. You can now iterate the results of the query both
+synchronously (with [method@Tracker.SparqlCursor.next]) or asynchronously
+(with [method@Tracker.SparqlCursor.next_async] and
+[method@Tracker.SparqlCursor.next_finish]).
+
+The [method@Tracker.SparqlConnection.query_statement] function can be used
+to obtain a [class@Tracker.SparqlStatement] object holding a prepared SPARQL
+query that can then be executed with [method@Tracker.SparqlStatement.execute].
+The query string can contain `~name` placeholders which can be replaced with
+arbitrary values before query execution with
+[method@Tracker.SparqlStatement.bind_string] and similar functions.
+This allows parsing the query string only once and to execute it multiple
+times with different parameters with potentially significant performance gains.
+
+Once you end up with the query, remember to call [method@Tracker.SparqlCursor.close].
+The same applies to [method@Tracker.SparqlConnection.close] when no longer needed.
+
+The following program shows how Read-Only queries can be done to the store in a
+synchronous way:
+
+```c
+{{examples/readonly-example.c}}
+```
+
+## Updating the store
+
+In order to perform updates in the store, a new writable
+[class@Tracker.SparqlConnection] object must be acquired with
+[ctor@Tracker.SparqlConnection.new].
+
+Once a proper connection object has been acquired, the update can
+be launched either synchronously ([method@Tracker.SparqlConnection.update])
+or asynchronously ([method@Tracker.SparqlConnection.update_async]).
+If launched asynchronously, the result of the operation can be obtained with
+[method@Tracker.SparqlConnection.update_finish].
+
+Once you no longer need the connection, remember to call
+[method@Tracker.SparqlConnection.close] on the [class@Tracker.SparqlConnection].
+
+The following program shows how a synchronous update can be done to the store:
+
+```c
+{{examples/writeonly-example.c}}
+```
+
+## Updating the store with blank nodes
+
+The majority of the work here is already described in the
+[previous example](#updating-the-store) where we talk about how to write the store.
+
+The difference with this example is that sometimes you want to
+insert data and have the URNs returned which were created to
+avoid re-querying for them. This is done using
+the [method@Tracker.SparqlConnection.update_blank] function (or asynchronously with
+[method@Tracker.SparqlConnection.update_blank_async]).
+If launched asynchronously, the result of the operation can be obtained with
+[method@Tracker.SparqlConnection.update_blank_finish]
+
+The `_:foo` in the example is how a blank node is
+represented in SPARQL. The `foo` part is used to generate the
+unique ID that is used for the new URN. It is also used in the
+`GVariant` that is returned. In the example below, we are creating
+a new blank node called `foo` for every class that exists.
+
+The format of the `GVariant` (in D-Bus terms) is `aaa{ss}` (an
+array of an array of dictionaries). This is rather complex but
+for a good reason. The first array represents each INSERT that
+may exist in the SPARQL. The second array represents each new
+node for a given WHERE clause (the example below illustrates
+this), you need this to differentiate between two INSERT
+statments like the one below in the same SPARQL sent to the
+store. Last, we have a final array to represent each new node's
+name (in this case `foo`) and the actual URN which was
+created. For most updates the first two outer arrays will only
+have one item in them.
+
+The following program shows how a synchronous blank node update can be done to the store:
+
+```c
+{{examples/writeonly-with-blank-nodes-example.c}}
+```
diff --git a/docs/reference/libtracker-sparql/examples.xml b/docs/reference/libtracker-sparql/examples.xml
deleted file mode 100644
index b0d1c0ef8..000000000
--- a/docs/reference/libtracker-sparql/examples.xml
+++ /dev/null
@@ -1,138 +0,0 @@
-<?xml version='1.0' encoding="ISO-8859-1"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2001/XInclude'">
-]>
-
-<part id="tracker-examples">
-  <title>Examples</title>
-  <partintro>
-    <para>
-      This chapters shows some real examples of usage of the Tracker SPARQL Library.
-    </para>
-  </partintro>
-
-  <chapter id="tracker-examples-readonly">
-    <title>Querying the Store</title>
-
-    <para>
-      First, a <type><link linkend="TrackerSparqlConnection-struct">TrackerSparqlConnection</link></type>
-      object must be acquired with
-      <function><link linkend="tracker-sparql-connection-get">tracker_sparql_connection_get</link></function>.
-      Then, a query can be launched either synchronously (<function><link linkend="tracker-sparql-connection-query">tracker_sparql_connection_query</link></function>)
-      or asynchronously (<function><link linkend="tracker-sparql-connection-query-async">tracker_sparql_connection_query_async</link></function>).
-      If launched asynchronously, the results of the query can be obtained with
-      <function><link linkend="tracker-sparql-connection-query-finish">tracker_sparql_connection_query_finish</link></function>.
-    </para>
-
-    <para>
-      If the query was successful, a <type><link linkend="TrackerSparqlCursor-struct">TrackerSparqlCursor</link></type>
-      will be available. You can now iterate the results of the query both synchronously (with
-      <function><link linkend="tracker-sparql-cursor-next">tracker_sparql_cursor_next</link></function>) or
-      asynchronously (with
-      <function><link linkend="tracker-sparql-cursor-next-async">tracker_sparql_cursor_next_async</link></function> and
-      <function><link linkend="tracker-sparql-cursor-next-finish">tracker_sparql_cursor_next_finish</link></function>)
-    </para>
-
-    <para>
-      The <function><link linkend="tracker-sparql-connection-query-statement">tracker_sparql_connection_query_statement</link></function>
-      function can be used to obtain a <link linkend="TrackerSparqlStatement">TrackerSparqlStatement</link> object holding a prepared SPARQL
-	    query that can then be executed with <function><link linkend="tracker-sparql-statement-execute">tracker_sparql_statement_execute</link></function>.
-	    The query string can contain <systemitem>~name</systemitem> placeholders which can be replaced with arbitrary values before query execution with the
-	    <function><link linkend="tracker-sparql-statement-bind-string">tracker_sparql_statement_bind_string</link></function> and similar functions.
-	    This allows parsing the query string only once and to execute it multiple times with different parameters with potentially significant performance gains.
-    </para>
-
-    <para>
-      The following program shows how Read-Only queries can be done to the store in a
-      synchronous way:
-      <informalexample>
-        <programlisting language="C">
-          <xi:include href="readonly-example.c" parse="text"/>
-        </programlisting>
-      </informalexample>
-    </para>
-  </chapter>
-
-  <chapter id="tracker-examples-writeonly">
-    <title>Updating the Store</title>
-
-    <para>
-      In order to perform updates in the store, a new
-      <type><link linkend="TrackerSparqlConnection-struct">TrackerSparqlConnection</link></type>
-      object must be acquired with
-      <function><link linkend="tracker-sparql-connection-get">tracker_sparql_connection_get</link></function>.
-      Once a proper connection object has been acquired, the update can be launched either
-      synchronously (<function><link linkend="tracker-sparql-connection-update">tracker_sparql_connection_update</link></function>)
-      or asynchronously (<function><link linkend="tracker-sparql-connection-update-async">tracker_sparql_connection_update_async</link></function>).
-      If launched asynchronously, the result of the operation can be obtained with
-      <function><link linkend="tracker-sparql-connection-update-finish">tracker_sparql_connection_update_finish</link></function>.
-    </para>
-
-    <para>
-      Once you no longer need the connection, remember to call <function><link linkend="g-object-unref">g_object_unref</link></function>
-      for the <type><link linkend="TrackerSparqlConnection-struct">TrackerSparqlConnection</link></type>.
-    </para>
-
-    <para>
-      The following program shows how a synchronous update can be done to the store:
-      <informalexample>
-        <programlisting language="C">
-          <xi:include href="writeonly-example.c" parse="text"/>
-        </programlisting>
-      </informalexample>
-    </para>
-  </chapter>
-
-  <chapter id="tracker-examples-writeonly-with-blank-nodes">
-    <title>Updating the Store with Blank Nodes</title>
-
-    <para>
-      The majority of the work here is already described in the
-      <link linkend="tracker-examples-writeonly">previous example</link> where we talk about how to write the store.
-    </para>
-
-    <para>
-      The difference with this example is that sometimes you want to
-      insert data and have the URNs returned which were created to
-      avoid re-querying for them. This is done using
-      the <function><link linkend="tracker-sparql-connection-update-blank">tracker_sparql_connection_update_blank</link></function> function (or asynchronously <function><link linkend="tracker-sparql-connection-update-blank-async">tracker_sparql_connection_update_blank_async</link></function>).
-      If launched asynchronously, the result of the operation can be obtained with
-      <function><link linkend="tracker-sparql-connection-update-blank-finish">tracker_sparql_connection_update_blank_finish</link></function>.
-    </para>
-
-    <para>
-      The <emphasis>_:foo</emphasis> in the example is how a blank node is
-      represented in SPARQL. The <emphasis>foo</emphasis> part is used to generate the
-      unique ID that is used for the new URN. It is also used in the
-      <function><link linkend="GVariant">GVariant</link></function>
-      that is returned. In the example below, we are creating a new
-      blank node called <emphasis>foo</emphasis> for every class that
-      exists.
-    </para>
-
-    <para>
-      The format of the GVariant (in D-Bus terms) is an aaa{ss} (an
-      array of an array of dictionaries). This is rather complex but
-      for a good reason. The first array represents each INSERT that
-      may exist in the SPARQL. The second array represents each new
-      node for a given WHERE clause (the example below illustrates
-      this), you need this to differentiate between two INSERT
-      statments like the one below in the same SPARQL sent to the
-      store. Last, we have a final array to represent each new node's
-      name (in this case <emphasis>foo</emphasis>) and the actual URN which was
-      created. For most updates the first two outer arrays will only
-      have one item in them.
-    </para>
-
-    <para>
-      The following program shows how a synchronous blank node update can be done to the store:
-      <informalexample>
-        <programlisting language="C">
-          <xi:include href="writeonly-with-blank-nodes-example.c" parse="text"/>
-        </programlisting>
-      </informalexample>
-    </para>
-  </chapter>
-
-</part>
diff --git a/docs/reference/libtracker-sparql/meson.build b/docs/reference/libtracker-sparql/meson.build
index 7a7e205d8..706e95f2e 100644
--- a/docs/reference/libtracker-sparql/meson.build
+++ b/docs/reference/libtracker-sparql/meson.build
@@ -1,6 +1,7 @@
 content = [
   'overview.md',
   'ontologies.md',
+  'examples.md',
   'limits.md',
   'performance.md',
   'sparql-and-tracker.md',