Updated README. Patch committed from Tshepang Lekhonkhobe.

	* README: Updated README. Patch committed from Tshepang Lekhonkhobe.

svn path=/trunk/; revision=2367

1 files changed, 79 insertions, 143 deletions

diff --git a/README b/README
index b9666d50e..ec933ba61 100644
--- a/README
+++ b/README
@@ -3,22 +3,21 @@ Table of Contents
     1 Introduction
     2 Use Cases
     3 Features
-    4 Minimum dependencies
-        4.1 Run-time dependencies (also needed for build)
-        4.2 Additional recommended dependencies
-        4.3 For building Tracker's Deskbar-applet backend
-        4.4 Optional run-time dependency
+    4 Dependencies
+        4.1 Recommended dependencies
+        4.2 For building Tracker's Deskbar-applet backend
     5 Compilation
         5.1 Notes on Solaris
         5.2 Compile Options
     6 Running Tracker
-        6.1 Setting Inotify Watch Limit
+        6.1 Usage
+        6.2 Setting Inotify Watch Limit
+        6.3 Tracker files
     7 Tracker & Nautilus Search
     8 Tracker & Deskbar applet
     9 Tracker tools
 
 
-
 1 Introduction
 
   Tracker is a powerful desktop-neutral first class object
@@ -52,14 +51,20 @@ Table of Contents
 
   All discussion related to tracker happens on the Tracker
   mailing list
-  (http://mail.gnome.org/mailman/listinfo/tracker-list) and/or
-  IRC channel #tracker on irc.gimp.net
+  
+        http://mail.gnome.org/mailman/listinfo/tracker-list
+
+  IRC channel #tracker on:
+
+        irc.gimp.net
+
+  Bugs should be filed at:
 
-  Bugs should be filed at http://bugzilla.gnome.org.
+        http://bugzilla.gnome.org.
 
   More infomation on Tracker can be found at
-  http://tracker-project.org.
 
+        http://tracker-project.org.
 
 
 2 Use Cases
@@ -72,7 +77,7 @@ Table of Contents
   * Provide search and indexing facilities similiar to those on
   other systems (Windows Vista and Mac OS X).
 
-  * Common database storage for all first class objects (EG a
+  * Common database storage for all first class objects (e.g. a
   common music/photo/contacts/email/bookmarks/history database)
   complete with additional metadata and tags/keywords.
 
@@ -117,6 +122,8 @@ Table of Contents
 
   * Provides option to disable indexing when running on battery.
 
+  * Provides option to index removable devices.
+
   * Implements the freedesktop specification for metadata
   (http://freedesktop.org/wiki/Standards/shared-filemetadata-spec).
 
@@ -145,22 +152,10 @@ Table of Contents
   * It auto-pauses indexing when running low on diskspace.
 
 
+4 Dependencies
 
-4 Minimum dependencies
-
-
-4.1 Run-time dependencies (also needed for build)
-
-  * SQLite 3.4
-  * libdbus 0.60
-  * dbus-glib bindings 0.60
-  * GLib 2.14
-  * zlib
-  * intltool 0.3.5
-  * GMime
 
-
-4.2 Additional recommended dependencies
+4.1 Recommended dependencies
 
   * GStreamer 0.10 + plugins for audio/video file indexing
   * xsltproc
@@ -172,32 +167,29 @@ Table of Contents
   * libpng
   * libexif
   * libgsf
-  * GTK and GNOME stack (for GUI tools)
   * libglade 2.5
+  * libxml2
+  * libxml2 (for extracting html/xml content)
   * unac (accent stripper)
   * exempi
-  * libxml2
+  * hal 0.5 (for detection of removable devices, mounted
+    directories, as well as whether the computer is running on
+    battery)
+  * GTK and GNOME stack (for GUI tools)
 
 
-4.3 For building Tracker's Deskbar-applet backend
+4.2 For building Tracker's Deskbar-applet backend
 
   * python-dev 2.3
   * python-gtk2-dev 2.3
   * deskbar-applet 2.16
 
 
-4.4 Optional run-time dependency
-
-  * xdg-utils (provides some functionality needed by
-  tracker-search-tool when in a non-GNOME environment)
-
-
-
 5 Compilation
 
   To compile and install Tracker, use the following commands :
 
-        ./configure --prefix=/usr --sysconfdir=/etc
+        ./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var
         make
         sudo make install
 
@@ -213,8 +205,12 @@ Table of Contents
   To compile Tracker with GCC on Solaris uses the following
   commands :
 
-        ./configure --prefix=/usr --sysconfdir=/etc --with-pic \
-        CFLAGS=-D_POSIX_PTHREAD_SEMANTICS
+        CFLAGS="-D_POSIX_PTHREAD_SEMANTICS" ./configure \
+	--prefix=/usr \
+	--sysconfdir=/etc \
+        --localstatedir=/var \
+	--with-pic
+
         make
         sudo make install
 
@@ -222,9 +218,13 @@ Table of Contents
   following commands, because there are some problems to compile
   exiv2 using SUN C++ compiler :
 
-        ./configure --prefix=/usr --sysconfdir=/etc --with-pic \
-        --disable-warnings \
-        --disable-exiv2 CFLAGS=-D_POSIX_PTHREAD_SEMANTICS
+        CFLAGS="-D_POSIX_PTHREAD_SEMANTICS" ./configure \
+	--prefix=/usr \
+	--sysconfdir=/etc \
+        --localstatedir=/var \
+	--with-pic \
+        --disable-exiv2
+
         make
         sudo make install
 
@@ -232,70 +232,25 @@ Table of Contents
 5.2 Compile Options
 
   Tracker has several compiler options to enable/disable certain
-  features. The following is a (hopefully complete) listing of
-  what's available:
-
-  --enable-debug-code : build with debug symbols
-
-  --enable-video-extractor=(gstreamer, xine, external, auto)
-
-  --enable-file-monitoring=(inotify, fam, polling, auto)
-
-  --disable-preferences : disables tracker-preferences capplet
-
-  --enable-deskbar-applet=(auto, handler, module) : enables
-  Deskbar-applet support; 'auto' should do since it automatically
-  chooses whether to install the 'handler' (for Deskbar-applet
-  >=2.16) or the 'module' (for Deskbar-applet >=2.19)
-
-  --with-deskbar-applet-dir=(directory where Deskbar-applet
-  should find tracker-handler; this should be automatically
-  detected, perhaps in
-  /usr/lib/deskbar-applet/{handlers,modules-2.20-compatible})
-
-  --disable-gui : disables tracker-search-tool build
-
-  --disable-pdf : disables the PDF data extractor
-
-  --disable-exif : disables the exif data extractor
-
-  --disable-libtrackergtk : disables libtracker-gtk build
-
-  --disable-gsf : disables the GSF data extractor
-
-  --disable-warnings : disables GCC warnings
-
-  --disable-unac : disables accent stripping
-
-  --disable-libxml2 : disables HTML/XML extractors (full-text
-  will still be available)
-
-  --disable-xmp : disables XMP extraction
-
-  --with-session-bus-services-dir=(path to D-Bus services
-  directory): this should be automatically detected
-
-  --enable-external-qdbm : use system qdbm instead of one included
-  in Tracker
-
-  --disable-hal : disables HAL support for ac-power detection
-
-  --disable-trackerapplet : disables Tracker's notification applet
+  features. You can get a full listing by running
 
+  	./configure --help
 
 
 6 Running Tracker
 
-  To run Tracker, you need to manually start the Tracker daemon,
-  trackerd. By default trackerd will index your entire home
-  directory.
+6.1 Usage
+
+  To run Tracker, you can manually start the Tracker daemon, 
+  trackerd. This is run for you if you issue a DBus call to the daemon
+  API.
 
   You can also pass a directory root to be indexed as a command
   line parameter if you dont want your entire home directory
-  indexed. EG "trackerd -i /home/jamie/Documents" (if you want
+  indexed, e.g. "trackerd -i /home/jamie/Documents" (if you want
   your home directory indexed when explicily specifying index
   directory roots then you must add your home directory to the
-  arguments: EG trackerd -i /home/jamie -i /mnt/share)
+  arguments: e.g. trackerd -i /home/jamie -i /mnt/share)
 
   You can disable indexing by passing "--no-indexing"
 
@@ -325,7 +280,7 @@ Table of Contents
 
   All the above options (and more) can be set by editing Tracker
   config file "~/.config/tracker/tracker.cfg" which is created
-  with specific defaults when non-existent (EG when trackerd is
+  with specific defaults when non-existent (e.g. when trackerd is
   ran for the first time). Ensure that you restart trackerd for
   the changes to take effect. "tracker.cfg" also provides options
   that allows Tracker to only index a subset of your home
@@ -333,13 +288,13 @@ Table of Contents
   by setting WatchDirectoryRoots to a semicolon-delimited list of
   directories (full path required!)
 
-  EG:
+  e.g.:
 
   "WatchDirectoryRoots=directory1;directory2;directory3""
 
-  An additional option is the "--reindex" option which indexes
-  user data from scratch, removing the need to remove Tracker
-  database manually.
+  An additional option is "--reindex" which indexes user data from
+  scratch, removing the need to delete Tracker's database manually.
+  Keywords and metadata definitions are preserved however.
 
   On the first run, Tracker will automatically create a new
   database and start populating it with metadata by browsing
@@ -351,11 +306,11 @@ Table of Contents
   changed since last index).
 
   If installed correctly, the Tracker daemon (trackerd) can also
-  be started automatically via Dbus activation (EG by running
+  be started automatically via Dbus activation (e.g. by running
   tracker-search SEARCHTERM)
 
 
-6.1 Setting Inotify Watch Limit
+6.2 Setting Inotify Watch Limit
 
   When watching large numbers of folders, its ppossible to exceed
   the default number of inotify watches. In order to get real time
@@ -364,12 +319,28 @@ Table of Contents
 
   1. Add this line to /etc/sysctl.conf:
      "fs.inotify.max_user_watches = (number of folders to be
-      watched; default is 8192)"
+      watched; default used to be 8192 and now is 524288)"
 
   2. Reboot the system OR (on a Debian-like system) run
      "sudo /etc/init.d/procps restart"
 
 
+6.3 Tracker files
+
+  Here is some of the files that Tracker uses during its operation,
+  apart from "~/.config/tracker" which is stated above, in Sec 6.1:
+
+  * "~/.local/share/tracker" is used for non-expendable content,
+    like keywords and metadata definitions.
+
+  * "~/.cache/tracker" is used for the expendable indexes and
+    expendable metadata that can be rebuilt if deleted (this is the
+    purpose of the ".cache" - its more a permanent tmp directory than
+    sys tmp but can be deleted if more disk space is needed).
+
+  * The system tmp ("/var/tmp" and "/tmp") is used for short-lived
+    session data.
+
 
 7 Tracker & Nautilus Search
 
@@ -387,50 +358,15 @@ Table of Contents
   desktop docs for how to achieve similar.
 
 
-
 8 Tracker & Deskbar applet
 
   Tracker is also integrated in GNOME's deskbar applet. See
   Compile Options above on how to get it built.
 
 
+9 Tracker Tools
 
-9 Tracker tools
-
-  Tracker comes with a number of utilities that you can use:
-
-  * "tracker-applet" - notification applet which has various
-  utilities like displaying Tracker status, indexing progress,
-  and live statistics, pausing indexing, and launching both
-  tracker-search-tool and tracker-preferences
-
-  * "tracker-extract FILE" - this extracts embedded metadata from
-  FILE and prints to stdout
-
-  * "tracker-files" - returns files filtered by the mime type or
-  their category (see the manpage)
-
-  * "tracker-meta-folder" - return list of files indexed by Tracker
-  for a folder
-
-  * "tracker-preferences" - GUI tool to set Tracker preferences
-
-  * "tracker-query" - this reads an RDF Query that specifies the
-  search criteria for various fields. It prints to STDOUT all
-  matching files. You can see some example queries in the
-  RDF-Query-examples folder. You can run the examples as
-  "tracker-query < RDFFILE"
-
-  * "tracker-search SEARCHTERM" - this perfoms a google like search
-  using SEARCHTERM to retrieve all matching files where
-  SEARCHTERM appears in any searchable metadata
-
-  * "tracker-search-tool SEARCHTERM" - GUI search utility
-
-  * "tracker-stats" - this displays the current number of indexed
-  items by category
-
-  * "tracker-status" - queries status of trackerd
-
-  * "tracker-tag" - used for setting and searching tags/keywords
+  Tracker comes with a number of utilities that you can use. These are
+  hosted in src/utils/. To find out how to use them, provide the
+  --help command line switch to know how to they are used.