[tracker] Add TrackerSparqlBuilder docs.

[Carlos Garnacho <carlosg src gnome org>]

commit 088d194842bb44c18e660e5432a9d995afbc62bb
Author: Carlos Garnacho <carlos lanedo com>
Date:   Tue Mar 9 13:35:45 2010 +0100

    Add TrackerSparqlBuilder docs.
    
    These had to be added to tmpl since the object is written in vala.

 .../tmpl/tracker-sparql-builder.sgml               |  374 ++++++++++++++++++++
 1 files changed, 374 insertions(+), 0 deletions(-)
---
diff --git a/docs/reference/libtracker-client/tmpl/tracker-sparql-builder.sgml b/docs/reference/libtracker-client/tmpl/tracker-sparql-builder.sgml
new file mode 100644
index 0000000..0d45872
--- /dev/null
+++ b/docs/reference/libtracker-client/tmpl/tracker-sparql-builder.sgml
@@ -0,0 +1,374 @@
+<!-- ##### SECTION Title ##### -->
+Sparql builder
+
+<!-- ##### SECTION Short_Description ##### -->
+Creating insertion/update SparQL queries.
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+#TrackerSparqlBuilder is an object what will gather a set of
+subject/predicate/object triples, together with an optional WHERE clause,
+in order to create a query that may be issued to tracker-store.
+</para>
+
+<para>
+When using #TrackerSparqlBuilder, note that you may append several predicates
+for the same subject, and several objects for the same predicate.
+</para>
+
+<example id="example-sparql-builder">
+  <title>Using TrackerSparqlBuilder</title>
+  <programlisting>
+  TrackerSparqlBuilder *builder;
+  const gchar *iri = "urn:example:0001";
+  gchar *query_str;
+&nbsp;&nbsp;
+  /* Create builder */
+  builder = tracker_sparql_builder_new_update ();
+&nbsp;&nbsp;
+  /* Drop previous data */
+  tracker_sparql_builder_drop_graph (builder, iri);
+&nbsp;&nbsp;
+  /* Insert new data */
+  tracker_sparql_builder_insert_open (builder, iri);
+&nbsp;&nbsp;
+  tracker_sparql_builder_subject_iri (builder, iri);
+&nbsp;&nbsp;
+  tracker_sparql_builder_predicate (builder, "a");
+  tracker_sparql_builder_object (builder, "nie:DataObject");
+  tracker_sparql_builder_object (builder, "nfo:FileDataObject");
+&nbsp;&nbsp;
+  tracker_sparql_builder_predicate (builder, "nfo:fileLastModified");
+  tracker_sparql_builder_object_date (builder, time (NULL));
+&nbsp;&nbsp;
+  tracker_sparql_builder_insert_close (builder);
+&nbsp;&nbsp;
+  /* Get query as string */
+  query_str = tracker_sparql_builder_get_result (builder);
+  </programlisting>
+</example>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+</para>
+
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### STRUCT TrackerSparqlBuilder ##### -->
+<para>
+The <structname>TrackerSparqlBuilder</structname> object represents an
+insertion/update SparQL query.
+</para>
+
+<!-- ##### STRUCT TrackerSparqlBuilderClass ##### -->
+<para>
+
+</para>
+
+ parent_class: 
+
+<!-- ##### STRUCT TrackerSparqlBuilderPrivate ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_new ##### -->
+<para>
+Creates a stateless #TrackerSparqlBuilder.
+</para>
+
+ Returns: a newly created #TrackerSparqlBuilder. Free with g_object_unref() when done
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_new_embedded_insert ##### -->
+<para>
+Creates a #TrackerSparqlBuilder ready to be embedded in another query. In embedded
+inserts, the subject is implied (responsibility of the embedder), so only calls to
+append predicates and objects for the given subject are allowed.
+</para>
+
+ Returns: a newly created #TrackerSparqlBuilder. Free with g_object_unref() when done
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_new_update ##### -->
+<para>
+Creates an empty #TrackerSparqlBuilder for an update query.
+</para>
+
+ Returns: a newly created #TrackerSparqlBuilder. Free with g_object_unref() when done
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_construct ##### -->
+<para>
+
+</para>
+
+ object_type: 
+ Returns: 
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_construct_embedded_insert ##### -->
+<para>
+
+</para>
+
+ object_type: 
+ Returns: 
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_construct_update ##### -->
+<para>
+
+</para>
+
+ object_type: 
+ Returns: 
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_get_result ##### -->
+<para>
+Returns the constructed SparQL query as a string.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ Returns: The created SparQL query.
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_get_length ##### -->
+<para>
+Returns the number of objects added to @self.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ Returns: The number of objects contained.
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_append ##### -->
+<para>
+Appends raw, unvalidated content to @self.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ raw: raw content to append.
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_prepend ##### -->
+<para>
+Prepends raw, unvalidated content to @self.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ raw: raw content to prepend.
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_insert_open ##### -->
+<para>
+Opens an insertion statement.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ graph: Graph name, or %NULL.
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_insert_close ##### -->
+<para>
+Closes an insertion statement opened with tracker_sparql_builder_insert_open ().
+</para>
+
+ self: a #TrackerSparqlBuilder
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_where_open ##### -->
+<para>
+Opens a WHERE clause. Data triples may be appended then to narrow the scope
+to which the update query applies.
+</para>
+
+ self: a #TrackerSparqlBuilder
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_where_close ##### -->
+<para>
+Closes a WHERE clause opened through tracker_sparql_builder_where_open().
+</para>
+
+ self: a #TrackerSparqlBuilder
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_delete_open ##### -->
+<para>
+Opens a DELETE clause. Data triples may be appended in order to prepare
+a query to delete them.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ graph: Graph name, or %NULL.
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_delete_close ##### -->
+<para>
+Closes a DELETE clause opened through tracker_sparql_builder_delete_close().
+</para>
+
+ self: a #TrackerSparqlBuilder
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_drop_graph ##### -->
+<para>
+Appends a DROP GRAPH clause.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ iri: a graph name.
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_subject_variable ##### -->
+<para>
+Appends a subject as a SparQL variable, such as "?urn".
+</para>
+
+ self: a #TrackerSparqlBuilder
+ var_name: Variable name, without leading '?'
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_subject_iri ##### -->
+<para>
+Appends a subject as an IRI, such as "&lt;urn:file:1234-5678&gt;". IRIs
+univocally identify a resource in tracker-store.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ iri: IRI name, without leading and trailing greater/less than symbols.
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_subject ##### -->
+<para>
+Appends a subject.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ s: subject string
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_predicate_iri ##### -->
+<para>
+Appends a predicate as an IRI.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ iri: IRI name, without leading and trailing greater/less than symbols.
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_predicate ##### -->
+<para>
+Appends a predicate for the previously appended subject.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ s: predicate string
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_object_iri ##### -->
+<para>
+Appends an object as an IRI.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ iri: IRI name, without leading and trailing greater/less than symbols.
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_object ##### -->
+<para>
+Appends a free-form object for the previously appended subject and predicate.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ s: object string
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_object_string ##### -->
+<para>
+Appends an object formatted as an string. @literal will be escaped and surrounded
+by double quotes.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ literal: string object
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_object_boolean ##### -->
+<para>
+Appends a #gboolean value as an object.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ literal: boolean object
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_object_int64 ##### -->
+<para>
+Appends a #gint64 as an object.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ literal: object as gint64
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_object_date ##### -->
+<para>
+Appends a time_t as an object. @literal will be converted to a
+string in the date format used by tracker-store.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ literal: object as time_t
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_object_double ##### -->
+<para>
+Appends a #gdouble as an object.
+</para>
+
+ self: a TrackerSparqlBuilder
+ literal: object as #gdouble
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_object_variable ##### -->
+<para>
+Appends an object as a SparQL variable, such as "?urn".
+</para>
+
+ self: a #TrackerSparqlBuilder
+ var_name: variable name, without leading '?'
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_object_blank_open ##### -->
+<para>
+Opens an anonymous blank node. In insertions this can be used to create
+anonymous nodes for not previously known data without the need of a
+separate insertion.
+</para>
+
+ self: a #TrackerSparqlBuilder
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_object_blank_close ##### -->
+<para>
+Closes an anomymous blank node opened with tracker_sparql_builder_object_blank_open()
+</para>
+
+ self: a #TrackerSparqlBuilder
+
+
+<!-- ##### FUNCTION tracker_sparql_builder_object_unvalidated ##### -->
+<para>
+Appends a string not validated as UTF-8 as an object.
+</para>
+
+ self: a #TrackerSparqlBuilder
+ value: possibly UTF-8 invalid string.
+
+