[tracker/libtracker-sparql: 52/55] libtracker-sparql: Added overview in documentation
- From: Jürg Billeter <juergbi src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [tracker/libtracker-sparql: 52/55] libtracker-sparql: Added overview in documentation
- Date: Fri, 6 Aug 2010 10:09:55 +0000 (UTC)
commit 60a6208fc17d42a48f615ba3a2e5755246984f92
Author: Aleksander Morgado <aleksander lanedo com>
Date: Wed Aug 4 16:13:48 2010 +0200
libtracker-sparql: Added overview in documentation
docs/reference/libtracker-sparql/Makefile.am | 2 +-
.../{examples.xml => examples.sgml} | 0
.../libtracker-sparql/libtracker-sparql-docs.sgml | 15 +--
docs/reference/libtracker-sparql/overview.sgml | 106 ++++++++++++++++++++
4 files changed, 110 insertions(+), 13 deletions(-)
---
diff --git a/docs/reference/libtracker-sparql/Makefile.am b/docs/reference/libtracker-sparql/Makefile.am
index 532e82b..e4ed68b 100644
--- a/docs/reference/libtracker-sparql/Makefile.am
+++ b/docs/reference/libtracker-sparql/Makefile.am
@@ -48,7 +48,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
+content_files = version.xml examples.sgml overview.sgml
expand_content_files =
diff --git a/docs/reference/libtracker-sparql/examples.xml b/docs/reference/libtracker-sparql/examples.sgml
similarity index 100%
rename from docs/reference/libtracker-sparql/examples.xml
rename to docs/reference/libtracker-sparql/examples.sgml
diff --git a/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml b/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml
index c1fbbb7..6d1a459 100644
--- a/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml
+++ b/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml
@@ -2,11 +2,12 @@
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY version SYSTEM "version.xml">
+<!ENTITY tracker-overview SYSTEM "overview.sgml">
<!ENTITY tracker-sparql-builder SYSTEM "xml/tracker-sparql-builder.xml">
<!ENTITY tracker-sparql-connection SYSTEM "xml/tracker-sparql-connection.xml">
<!ENTITY tracker-sparql-cursor SYSTEM "xml/tracker-sparql-cursor.xml">
<!ENTITY tracker-misc SYSTEM "xml/tracker-misc.xml">
-<!ENTITY tracker-examples SYSTEM "examples.xml">
+<!ENTITY tracker-examples SYSTEM "examples.sgml">
]>
<book id="index">
<bookinfo>
@@ -15,17 +16,7 @@
</bookinfo>
<!-- The Library Overview -->
- <part id="libtracker-sparql-overview">
- <title>Overview</title>
- <partintro>
- <para>
- The libtracker-sparql library is the foundation for Tracker
- querying and inserting into the data store. The data store
- allows both querying and inserting using SPARQL based on the
- Nepomuk ontology.
- </para>
- </partintro>
- </part>
+ &tracker-overview;
<!-- The API Reference -->
<part id="libtracker-sparql-reference">
diff --git a/docs/reference/libtracker-sparql/overview.sgml b/docs/reference/libtracker-sparql/overview.sgml
new file mode 100644
index 0000000..7fb08a9
--- /dev/null
+++ b/docs/reference/libtracker-sparql/overview.sgml
@@ -0,0 +1,106 @@
+<?xml version='1.0' encoding="ISO-8859-1"?>
+
+<part id="tracker-overview">
+ <title>Overview</title>
+ <partintro>
+ <para>
+ The libtracker-sparql library is the foundation for Tracker
+ querying and inserting into the data store. The data store
+ allows both querying and inserting using SPARQL based on the
+ Nepomuk ontology.
+ </para>
+ </partintro>
+
+
+ <chapter id="tracker-overview-connection-methods">
+ <title>Connection methods</title>
+
+ <para>
+ The Tracker SPARQL library provides several underlying methods to connect
+ to the Tracker Store:
+ <itemizedlist>
+ <listitem>
+ <emphasis>Direct Access:</emphasis>
+ <para>
+ All Read-Only operations done in a
+ <type><link linkend="TrackerSparqlConnection-struct">TrackerSparqlConnection</link></type>
+ will by default use this method, as it doesn't involve any D-Bus traffic,
+ and thus, it will perform much better. There is no real connection with
+ the Tracker Store in this case, as the access is direct to the underlying
+ SQLite database. Again, note that this method applies only to
+ <emphasis>Read-Only</emphasis> operations.
+ </para>
+ <para>
+ If you plan to only do Read-Only queries to the store, you can get the
+ <type><link linkend="TrackerSparqlConnection-struct">TrackerSparqlConnection</link></type>
+ object using <function><link linkend="tracker-sparql-connection-get-direct">tracker_sparql_connection_get_direct</link></function>. Otherwise, if you also plan to use the same connection object
+ for updates, you must get the connection object with
+ <function><link linkend="tracker-sparql-connection-get">tracker_sparql_connection_get</link></function>.
+ </para>
+ </listitem>
+ <listitem>
+ <emphasis>D-Bus FD passing:</emphasis>
+ <para>
+ If the system runs a D-Bus ≥ 1.3.1, the
+ <type><link linkend="TrackerSparqlConnection-struct">TrackerSparqlConnection</link></type>
+ will use the File Descriptor passing method via D-Bus to connect to the Store,
+ which is faster than the plain D-Bus for queries involving a lot of traffic.
+ This method will be used for all non read-only queries on
+ <type><link linkend="TrackerSparqlConnection-struct">TrackerSparqlConnection</link></type>
+ objects obtained with
+ <function><link linkend="tracker-sparql-connection-get">tracker_sparql_connection_get</link></function>.
+ </para>
+ </listitem>
+ <listitem>
+ <emphasis>D-Bus:</emphasis>
+ <para>
+ If the system runs a D-Bus < 1.3.1, the
+ <type><link linkend="TrackerSparqlConnection-struct">TrackerSparqlConnection</link></type>
+ will use the standard D-Bus method to connect to the Store.
+ This method will be used for all non read-only queries on
+ <type><link linkend="TrackerSparqlConnection-struct">TrackerSparqlConnection</link></type>
+ objects obtained with
+ <function><link linkend="tracker-sparql-connection-get">tracker_sparql_connection_get</link></function>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </chapter>
+
+
+ <chapter id="tracker-overview-compiling">
+ <title>Compiling applications</title>
+
+ <para>
+ To compile applications using libtracker-sparql, you
+ need to tell the compiler where to find the proper header files
+ and libraries. This is done with the
+ <application>pkg-config</application> utility.
+ </para>
+
+ <para>
+ The following interactive shell session demonstrates how
+ <application>pkg-config</application> is used (the actual output on
+ your system may be different):
+<programlisting>
+$ pkg-config --cflags tracker-sparql-0.9
+ -pthread -I/usr/include/tracker-0.9 -I/usr/include/tracker-0.9/libtracker-sparql -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include
+
+$ pkg-config --libs tracker-sparql-0.9
+ -Wl,--export-dynamic -pthread -ltracker-sparql-0.9 -lgio-2.0 -lgobject-2.0 -lgmodule-2.0 -lgthread-2.0 -lrt -lglib-2.0
+</programlisting>
+ </para>
+ <para>
+ The simplest way to compile a program is to use the "backticks"
+ feature of the shell. If you enclose a command in backticks
+ (<emphasis>not single quotes</emphasis>), then its output will be
+ substituted into the command line before execution:
+<programlisting>
+ $ cc `pkg-config --cflags --libs tracker-sparql-0.9` hello.c -o hello
+</programlisting>
+ </para>
+
+ </chapter>
+
+</part>
+
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]