General clean-up and documentation.
diff --git a/INSTALL b/INSTALL
index 20a565b..e592c46 100644
--- a/INSTALL
+++ b/INSTALL
@@ -1,14 +1,164 @@
INSTALLATION OVERVIEW
=====================
-COMPILATION
------------
+Once libmtp is built and installed, you will have the following files
+($PREFIX is the --prefix option given to the "configure" script and
+defaults to /usr/local/):
-Problems with compilation under FC4: GCC4 related problem.
-Run this:
+ $PREFIX/lib/libmtp.a Static C library
+ $PREFIX/lib/libmtp.so.x.y.z Dynamic C library
+ $PREFIX/lib/libmtp.so.x A link to the library
+ $PREFIX/lib/libmtp.so A link to the library
+ $PREFIX/include/libmtp.h C header file for libmtp API
+ $PREFIX/lib/pkgconfig/libmtp.pc pkg-config configuration file
-CC=gcc32
-export CC
-./configure
-make
+Sample programs will be built in the "example" directory, and should
+help you get used to using the libmtp API, as well as provide some
+immediate gratification. Links to other programs using the libmtp
+API may be found at the homepage: http://libmtp.sourceforge.net/
+Shared Library Support
+----------------------
+
+Shared library linking is supported. You will need to 'make install'
+the library before you can execute the sample binaries, and add the
+libmtp install directory to your shared library search path.
+
+On Linux, you would add the line "/usr/local/lib" to your
+"/etc/ld.so.conf" or as a oneliner in for example a
+"/etc/ld.so.conf.d/local.conf" file and run the
+program "ldconfig" to scan in the shared libraries at
+the new path. This is a part of the Linux shared library
+loader actually.
+
+To access the library from real odd locations you can use
+the LD_LIBRARY_PATH environment variable by setting it before
+you run your program, for example:
+
+ % export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
+ % my_program
+
+This way of enabling the library to link is a workaround hack.
+Note that the LD_LIBRARY_PATH is actually supposed to be used for
+testing, not production systems or distributions. It is commonly
+used as a workaround when a user is installing libraries in her/his
+home directory however. Read more about this environment variable
+here: http://www.visi.com/~barr/ldpath.html
+
+The shared library comes with different interface version numbers,
+for example libmtp.so.4, libmtp.so.5 and so forth. This is used so
+that both old and new libmtp libraries shall be able to coexist on
+the same system. When you compile your programs they will typically
+bind to the latest version of the shared library. A link to the
+latest version is always provided as $PREFIX/lib/libmtp.so.
+
+libusb Support
+--------------
+
+This package depends on libusb. Get libusb from sourceforge at:
+
+ http://www.sourceforge.net/projects/libusb/
+
+
+BASIC BUILD PROCEDURE
+=====================
+
+To build the package:
+
+ % ./configure
+ % make
+ % make install
+
+By default, libmtp will add the program-prefix "mtp-" to all the
+example programs prior to installation. The program-prefix option
+makes libmtp sample programs avoid collision with other programs like
+sox' "play" program. On Linux you should then typically type (see
+below for details):
+
+ % ./hotplug.sh
+
+you can achieve the same with
+
+ % ./configure --enable-hotplugging
+
+you can turn off some speed enhancements (for testing) with:
+
+ % ./configure --no-turbo
+
+if you want to install the documentation type:
+
+ % make install-docs
+
+if you checked out the sources from CVS, you must first run the
+autogen.sh script that generates all the GNU autotools files.
+Notice that this requires GNU autoconf, automake and libtool. This
+is done with:
+
+ % ./autogen.sh
+
+
+Linux hotplugging
+-----------------
+
+After compilation and installation you may (and should) add hotplugging
+support by running the hotplug script, if your distribution supports
+hotplugging (all do). This typically means you have something
+in /etc/hotplug and that hotplugging is started when you boot your
+machine in a script named /etc/init.d/hotplug or similar.
+
+Activate hotplugging by running:
+
+ %./hotplug.sh
+
+Hotplug will (typically) use the device map file installed by hotplug.sh
+at /etc/hotplug/usb/libmtp.usermap to lift the device to userspace for the
+current user by running the script /etc/hotplug/usb/libmtp.sh. If
+you have the program "resmgr" installed (currently used only by SuSE to
+our knowledge) that program will be used for enabling desktop user
+access, otherwise the current user of the desktop will be determined
+from files in /var/run. (See the script "libmtp.sh" for details.)
+
+
+Linux udev hotplugging
+----------------------
+
+Newer Linux distributions have dropped support for the old hotplug system
+and rely solely on udev, and rules stored below /etc/udev/rules.d to
+handle permissions and actions on device connections. It's quite solid
+but the whole thing is rather shaky when it comes to such things as
+custom devices handled solely by libusb, which is what libmtp and for
+example SANE backends use.
+
+The libmtp.rules file that comes with libmtp can be used as a starter.
+
+First you need a crazy rule that creates a device node in the
+/dev/bus/usb hierarchy whenever any USB device is connected. The
+script has this at the top, you can comment it in if your
+distribution does not already create these device nodes.
+
+Then libusb may need to be patched to recognize this hierarchy.
+The 0.1.12 version is the first which is properly fixed.
+
+The script sets the device access to "666" which is rather nasty
+(not that big security issue, unless you think someone will break
+into your jukebox) some systems prefer to let PAM do this by placing
+a configuration file in /etc/security/ somewhere. See the Fedora Extras
+SRPM source package in case you're interested in how it is handled
+there.
+
+
+If you cannot run hotplugging
+-----------------------------
+
+If you have a distro without hotplugging enabled try this as root:
+
+ % chmod -R a+w /proc/bus/usb
+
+You have to do this again every time you unplug/replug your USB cable
+or restart the jukebox, every time you quit libnjb and restart it,
+etc etc etc an alternative is to run libmtp as root which works just fine.
+The problem is to somehow assure that you (ie the current user) always
+has write access on /proc/bus/usb/*
+
+You can find the Linux hotplug project at:
+http://linux-hotplug.sourceforge.net/