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

[Aleksander Morgado <aleksm src gnome org>]

commit c041ceafd2b45aaeadb0a7d2a003145ba5f4e814
Author: Aleksander Morgado <aleksander lanedo com>
Date:   Tue Feb 8 12:04:13 2011 +0100

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

 docs/reference/libtracker-extract/Makefile.am      |    3 +-
 .../libtracker-extract-docs.sgml                   |   30 +++++------
 docs/reference/libtracker-extract/overview.sgml    |   51 ++++++++++++++++++++
 3 files changed, 66 insertions(+), 18 deletions(-)
---
diff --git a/docs/reference/libtracker-extract/Makefile.am b/docs/reference/libtracker-extract/Makefile.am
index 04ed088..4f6a390 100644
--- a/docs/reference/libtracker-extract/Makefile.am
+++ b/docs/reference/libtracker-extract/Makefile.am
@@ -43,8 +43,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-extract/libtracker-extract-docs.sgml b/docs/reference/libtracker-extract/libtracker-extract-docs.sgml
index 213abda..6c0a7d5 100644
--- a/docs/reference/libtracker-extract/libtracker-extract-docs.sgml
+++ b/docs/reference/libtracker-extract/libtracker-extract-docs.sgml
@@ -1,12 +1,13 @@
 <?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-data SYSTEM "xml/tracker-data.xml">
 <!ENTITY tracker-utils SYSTEM "xml/tracker-utils.xml">
 <!ENTITY tracker-xmp SYSTEM "xml/tracker-xmp.xml">
 <!ENTITY tracker-iptc SYSTEM "xml/tracker-iptc.xml">
 <!ENTITY tracker-exif SYSTEM "xml/tracker-exif.xml">
-<!ENTITY version SYSTEM "version.xml">
 ]>
 <book id="index">
   <bookinfo>
@@ -14,32 +15,29 @@
     <releaseinfo>for libtracker-extract &version;</releaseinfo>
   </bookinfo>
 
-  <part id="libtracker-extract">
-    <title>Overview</title>
+  <!-- The Library Overview -->
+  &tracker-overview;
+
+  <!-- The API Reference -->
+  <part id="libtracker-extract-reference">
+    <title>Reference</title>
     <partintro>
       <para>
-        The libtracker-extract library is the foundation for Tracker
-        metadata extraction of embedded data in files. Tracker comes
-        with extractors written for the most common file types (like
-        MP3, JPEG, PNG, etc.), however, for more special cases, 3rd
-        party applications may want to write their own plugin to
-        extract their own file formats. This documentation describes
-        how to do that.
-      </para>
-      <para>
+        This section provides the detailed API of the Tracker Extract library.
       </para>
     </partintro>
-  </part>
 
     <chapter>
-      <title>Core</title>
+      <title>Core API</title>
       &tracker-data;
       &tracker-utils;
     </chapter>
+
     <chapter>
-      <title>Common Embedded Support</title>
+      <title>Common Embedded Support API</title>
       &tracker-xmp;
       &tracker-iptc;
       &tracker-exif;
     </chapter>
+  </part>
 </book>
diff --git a/docs/reference/libtracker-extract/overview.sgml b/docs/reference/libtracker-extract/overview.sgml
new file mode 100644
index 0000000..80f2416
--- /dev/null
+++ b/docs/reference/libtracker-extract/overview.sgml
@@ -0,0 +1,51 @@
+<?xml version='1.0' encoding="ISO-8859-1"?>
+
+<part id="tracker-overview">
+  <title>Overview</title>
+  <partintro>
+    <para>
+      The libtracker-extract library is the foundation for Tracker
+      metadata extraction of embedded data in files. Tracker comes
+      with extractors written for the most common file types (like
+      MP3, JPEG, PNG, etc.), however, for more special cases, 3rd
+      party applications may want to write their own plugin to
+      extract their own file formats. This documentation describes
+      how to do that.
+    </para>
+  </partintro>
+
+  <chapter id="tracker-overview-compiling">
+    <title>Compiling applications</title>
+
+    <para>
+      To compile applications using libtracker-extract, 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-extract-0.10
+-I/usr/include/tracker-0.10 -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include
+
+$ pkg-config --libs tracker-extract-0.10
+-ltracker-extract-0.10 -ltracker-client-0.10 -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-extract-0.10` hello.c -o hello
+</programlisting>
+    </para>
+
+  </chapter>
+</part>