[tracker/0.10-documentation-review: 9/11] docs, libtracker-miner: Cleanup sections and added new 'Compiling applications' one

[Aleksander Morgado <aleksm src gnome org>]

commit 422442125e0231f4294fb372782fb56074f17dbc
Author: Aleksander Morgado <aleksander lanedo com>
Date:   Tue Feb 8 12:22:38 2011 +0100

    docs, libtracker-miner: Cleanup sections and added new 'Compiling applications' one

 docs/reference/libtracker-miner/Makefile.am        |    3 +-
 .../libtracker-miner/libtracker-miner-docs.sgml    |   35 ++++++++------
 docs/reference/libtracker-miner/overview.sgml      |   47 ++++++++++++++++++++
 3 files changed, 68 insertions(+), 17 deletions(-)
---
diff --git a/docs/reference/libtracker-miner/Makefile.am b/docs/reference/libtracker-miner/Makefile.am
index 5b0f236..b4174fd 100644
--- a/docs/reference/libtracker-miner/Makefile.am
+++ b/docs/reference/libtracker-miner/Makefile.am
@@ -57,8 +57,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 overview.sgml
 
 expand_content_files =
 
diff --git a/docs/reference/libtracker-miner/libtracker-miner-docs.sgml b/docs/reference/libtracker-miner/libtracker-miner-docs.sgml
index a1dd867..dd3f33c 100644
--- a/docs/reference/libtracker-miner/libtracker-miner-docs.sgml
+++ b/docs/reference/libtracker-miner/libtracker-miner-docs.sgml
@@ -1,6 +1,8 @@
 <?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
+<!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-miner SYSTEM "xml/tracker-miner.xml">
 <!ENTITY tracker-miner-fs SYSTEM "xml/tracker-miner-fs.xml">
 <!ENTITY tracker-miner-manager SYSTEM "xml/tracker-miner-manager.xml">
@@ -9,7 +11,6 @@
 <!ENTITY tracker-password-provider SYSTEM "xml/tracker-password-provider.xml">
 <!ENTITY tracker-storage SYSTEM "xml/tracker-storage.xml">
 <!ENTITY tracker-thumbnailer SYSTEM "xml/tracker-thumbnailer.xml">
-<!ENTITY version SYSTEM "version.xml">
 ]>
 <book id="index">
   <bookinfo>
@@ -17,29 +18,26 @@
     <releaseinfo>for libtracker-miner &version;</releaseinfo>
   </bookinfo>
 
-  <part id="libtracker-miner">
-    <title>Overview</title>
+  <!-- The Library Overview -->
+  &tracker-overview;
+
+  <!-- The API Reference -->
+  <part id="libtracker-miner-reference">
+    <title>Reference</title>
     <partintro>
       <para>
-        The libtracker-miner library is the foundation for Tracker data miners,
-        these miners will extract metadata and insert it in SPARQL form to
-        tracker-store, following the Nepomuk ontology.
-      </para>
-      <para>
+        This section provides the detailed API of the Tracker Miner library.
       </para>
     </partintro>
-  </part>
 
     <chapter>
-      <title>Base abstract miner class</title>
+      <title>Base abstract miners</title>
       &tracker-miner;
       &tracker-miner-web;
-      &tracker-network-provider;
-      &tracker-password-provider;
     </chapter>
 
     <chapter>
-      <title>Helper implementations</title>
+      <title>Additional miners</title>
       &tracker-miner-fs;
     </chapter>
 
@@ -49,8 +47,15 @@
     </chapter>
 
     <chapter>
-      <title>Utilities</title>
+      <title>Base abstract utilities</title>
+      &tracker-network-provider;
+      &tracker-password-provider;
+    </chapter>
+
+    <chapter>
+      <title>Additional utilities</title>
       &tracker-storage;
       &tracker-thumbnailer;
     </chapter>
+  </part>
 </book>
diff --git a/docs/reference/libtracker-miner/overview.sgml b/docs/reference/libtracker-miner/overview.sgml
new file mode 100644
index 0000000..8f59719
--- /dev/null
+++ b/docs/reference/libtracker-miner/overview.sgml
@@ -0,0 +1,47 @@
+<?xml version='1.0' encoding="ISO-8859-1"?>
+
+<part id="tracker-overview">
+  <title>Overview</title>
+  <partintro>
+    <para>
+      The libtracker-miner library is the foundation for Tracker data miners,
+      these miners will extract metadata and insert it in SPARQL form to
+      tracker-store, following the Nepomuk ontology.
+    </para>
+  </partintro>
+
+  <chapter id="tracker-overview-compiling">
+    <title>Compiling applications</title>
+
+    <para>
+      To compile applications using libtracker-miner, 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-miner-0.10
+-pthread -I/usr/include/tracker-0.10 -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -I/usr/include/tracker-0.10/libtracker-sparql
+
+$ pkg-config --libs tracker-miner-0.10
+-pthread -Wl,--export-dynamic -ltracker-miner-0.10 -ltracker-sparql-0.10 -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-miner-0.10` hello.c -o hello
+</programlisting>
+    </para>
+
+  </chapter>
+</part>