[tracker] libtracker-sparql: Add migration docs

[Carlos Garnacho <carlosg src gnome org>]

commit 27b2aec5e658599beb17ebdfa39fe325e4387eeb
Author: Carlos Garnacho <carlosg gnome org>
Date:   Mon Aug 7 12:10:30 2017 +0200

    libtracker-sparql: Add migration docs

 docs/reference/libtracker-sparql/Makefile.am       |    2 +-
 .../libtracker-sparql/libtracker-sparql-docs.sgml  |    1 +
 docs/reference/libtracker-sparql/meson.build       |    2 +-
 .../reference/libtracker-sparql/migrating-1to2.xml |   57 ++++++++++++++++++++
 4 files changed, 60 insertions(+), 2 deletions(-)
---
diff --git a/docs/reference/libtracker-sparql/Makefile.am b/docs/reference/libtracker-sparql/Makefile.am
index 9ba68dc..790b382 100644
--- a/docs/reference/libtracker-sparql/Makefile.am
+++ b/docs/reference/libtracker-sparql/Makefile.am
@@ -51,7 +51,7 @@ MKDB_OPTIONS = --sgml-mode --output-format=xml
 MKHTML_OPTIONS=--path="$(abs_builddir)"
 
 # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE)
-content_files =        version.xml examples.sgml overview.sgml ontologies.sgml
+content_files =        version.xml examples.sgml overview.sgml ontologies.sgml migrating-1to2.xml
 
 expand_content_files =
 
diff --git a/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml 
b/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml
index bedea92..0c6b28c 100644
--- a/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml
+++ b/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml
@@ -49,6 +49,7 @@
 
   <xi:include href="ontologies.sgml"/>
   <xi:include href="examples.sgml"/>
+  <xi:include href="migrating-1to2.xml"/>
 
   <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
 </book>
diff --git a/docs/reference/libtracker-sparql/meson.build b/docs/reference/libtracker-sparql/meson.build
index b22df85..173a107 100644
--- a/docs/reference/libtracker-sparql/meson.build
+++ b/docs/reference/libtracker-sparql/meson.build
@@ -5,5 +5,5 @@ version_xml = configure_file(input: 'version.xml.in',
 gnome.gtkdoc('libtracker-sparql',
     src_dir: 'src/libtracker-sparql',
     main_sgml: 'libtracker-sparql-docs.sgml',
-    content_files: ['overview.sgml', 'examples.sgml'],
+    content_files: ['overview.sgml', 'examples.sgml', 'migrating-1to2.xml'],
     install: true)
diff --git a/docs/reference/libtracker-sparql/migrating-1to2.xml 
b/docs/reference/libtracker-sparql/migrating-1to2.xml
new file mode 100644
index 0000000..ce36aa8
--- /dev/null
+++ b/docs/reference/libtracker-sparql/migrating-1to2.xml
@@ -0,0 +1,57 @@
+<?xml version='1.0'?>
+
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"; [
+<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+]>
+<chapter id="tracker-migrating-1-to-2">
+  <title>Migrating from libtracker-sparql 1.x to 2.0</title>
+
+  <para>
+    Tracker 2.0 is a new major version, containing some possibly
+    incompatible changes. Most of the changes are not hard to adapt,
+    and even unlikely to be a problem if the ported application was
+    kept up-to-date in its usage of 1.x.
+  </para>
+
+  <section>
+    <title>Stricter SPARQL1.1</title>
+    <para>
+      Tracker supports a large subset of the SPARQL1.1 definition,
+      and offers a number of nonstandard features that are useful.
+      There is however one nonstandard feature that brings no
+      added value.
+    </para>
+    <programlisting>
+# These were equivalent in Tracker 1.x
+SELECT ?u AS ?foo WHERE { ?u ... }
+SELECT ?u AS foo WHERE { ?u ... }
+    </programlisting>
+    <para>
+      The latter form is not observed in the SPARQL1.1 spec, and
+      support for it has been dropped in Tracker 2.0. If you want
+      to make queries that work on both Tracker 2.0 and 1.x, use
+      the former form, which has also been supported for a long
+      time in 1.x.
+    </para>
+  </section>
+
+  <section>
+    <title>No getters for direct/bus SPARQL connections</title>
+    <para>
+      Those have been deprecated for a long time in 1.x and have
+      been removed for 2.0. Use tracker_sparql_connection_get(),
+      which will smartly use direct/bus connections underneath
+      depending on the type of query.
+    </para>
+  </section>
+
+  <section>
+    <title>TrackerSparqlBuilder is deprecated</title>
+    <para>
+      Users are encouraged to use TrackerResource, included in
+      the last 1.x releases, and now being the preferred method
+      to create SPARQL updates for your data.
+    </para>
+  </section>
+</chapter>