More documentation updates.

1 files changed, 47 insertions, 51 deletions

diff --git a/INSTALL b/INSTALL
index 9c3034c2..b4182d51 100644
--- a/INSTALL
+++ b/INSTALL
@@ -1,9 +1,16 @@
 = GPSD Installation Instructions =
 
-Here are the steps for installing GPSD and verifying its performance:
+Here are the steps for installing GPSD and verifying its performance.
+They assume you have GPSD available as an installable binary package, 
+
+Whatever distribution you are running, the name of the core GPSD
+package containing the service daemon is almost certainly "gpsd".
+However, many distributions break up GPSD into separate installable
+packages for the core daemon and clients; you should search your
+repository index for anything with gpsd as a prefix.
 
 Instructions for building GPSD from source (including cross-building)
-are in the file "build.txt"
+are in the file "build.txt" in the source distribution.
 
 == Check that your GPS is live and you can get data from it ==
 
@@ -29,21 +36,9 @@ using an RS-232 port (which is no longer common) you will need
 serial-port support compiled into your kernel.  Various USB-to-serial
 adapter chips found in GPSes require specific drivers.
 
-Under a stock Linux kernel these will akll be loaded on demand when
+Under a stock Linux kernel these will all be loaded on demand when
 the USB system sees the appropriate vendor/product ID combinations.
-If you have or are custom-building a Linux kernel for embedded
-deployment, you will need some subset of the following modules:
-
-pl2303        Prolific Technology, Inc. PL2303 Serial Port
-ftdi_sio      FTDI 8U232AM / FT232
-cypress_m8    M8/CY7C64013
-cp210x        Cygnal Integrated Products devices
-garmin_gps    Garmin USB mice including GPS-18
-cdc_am        USB Communication Device Class Abstract Control Model interface
-
-These are listed in rough order of devices covered as of 2011; the
-PL23203 by itself accounts for over 70% of deployed USB mice.  We
-recommend building with pl2303, ftdi_sio, cypress_m8, and cp210x.
+See build.txt for instructions relating to custom kernels.
 
 == Check that your system configuration will allow GPSD to work ==
 
@@ -85,13 +80,15 @@ A minimum build of GPSD can run pretty close to the metal; all it
 absolutely needs is the C runtime support. The test clients and
 various additional features have additional prerequisites:
 
-pthreads library       -> support for PPS timekeeping on serial GPSes
-DBUS                   -> gpsd will issue DBUS notifications 
-ncurses                -> a test client and the GPS monitor depend on this
-libusb-1.0.x or later  -> better USB device discovery
-Qt + qmake             -> libQgpsmm depends on this
-python2.6+             -> required for various clients and utilities
-pgtk-2/cairo bindings  -> the main test client, xgps, needs this
+|==========================================================================
+|pthreads library       | support for PPS timekeeping on serial GPSes
+|DBUS                   | gpsd will issue DBUS notifications 
+|ncurses                | a test client and the GPS monitor depend on this
+|libusb-1.0.x or later  | better USB device discovery
+|Qt + qmake             | libQgpsmm depends on this
+|python2.6+             | required for various clients and utilities
+|pgtk-2/cairo bindings  | the main test client, xgps, needs this
+|==========================================================================
 
 Note that while Python is required to *build* GPSD from source (the
 build uses some code generators in Python), it is not required to run
@@ -102,19 +99,13 @@ The Python code in GPSD is actually compatible back to Python 2.4 except that
 you need either the json library module from 2.6 or the functionally
 equivalent simplejson backport.
 
-== Building and installing the software ==
-
-If you have GPSD available as a binary package, its name is almost
-certainly "gpsd".  However, many distributions break up GPSD into
-separate installable packages for the core daemon and clients; you
-should search your repository index for anything with gpsd as a prefix.
-
-Instructions for building from source are in the file "build.txt".
-
 == How to test the software ==
 
 1. Start gpsd.  You'll need to give it as an argument a path to 
-a serial or USB port with a GPS attached to it.
+a serial or USB port with a GPS attached to it.  Your test command
+should look something like this:
+
+       gpsd -D 5 -N -n /dev/ttyUSB0
 
 2. Once gpsd is running, telnet to port 2947. You should see a
 greeting line that's a JSON object describing GPSD's version.
@@ -125,19 +116,26 @@ watcher modes.  You should see lines beginning with '{' that are
 JSON objects representing reports from your GPS; these are reports
 in GPSD protocol.
 
-4. Start the xgps client.  Calling it with no arguments should do the right 
-thing.  You should see a GUI panel with position/velocity-time information,
-and a satellite display.  The displays won't look very interesting until 
-the GPS acquires satellite lock.
+4. Start the xgps or cgps client.  Calling it with no arguments should
+do the right thing.  You should see a display panel with
+position/velocity-time information, and a satellite display.  The
+displays won't look very interesting until the GPS acquires satellite
+lock.
 
 5. Have patience.  If you are cold-starting a new GPS, it may take
 15-20 minutes after it gets a skyview for it to download an ephemeris
 and begin delivering fixes.
 
-6. To enable hotplugging of USB GPSes under Linux, do a 'scons udev-install' or
-equivalent to put the appropriate udev rules and wrapper files in place.
+6. A FAQ and troubleshooting instructions can be found at
+http://gpsd.berlios.de/faq.html
 
-7. Check out the list of supported hardware at 
+== Once you have verified correct operation ==
+
+1. If you installed from a .deb under Debian or a Debian-derived 
+system, you may need to `dpkg-reconfigure -plow gpsd' to enable the
+hotplug magic ("Start gpsd automatically").
+
+2. Check out the list of supported hardware at 
 
    http://gpsd.berlios.de/hardware.html
 
@@ -147,19 +145,17 @@ line to the table.  Directions are included on that page.
 We can also use updates of the latest version number known to work with
 hardware already supported.
 
-8. The distribution includes a PHP script that you can use to
-generate a PHP status page for your GPS.  You will need php and php-gd
-installed.  To install it, copy the file 'gpsd.php' to your HTTP
-document directory.  The first time it's invoked, it will generate a
-file called 'gpsd_config.inc' containing configuration information;
-edit to taste.  Note that for the Google Maps feature work you need
-to set a valid Google API key in your config file.
+3. GPSD includes a PHP script that you can use to generate a PHP
+status page for your GPS if you wish. (It may not be in the core
+package.)  
 
-9. If you installed from a .deb under Debian or a Debian-derived 
-system, you may need to `dpkg-reconfigure -plow gpsd' to enable the
-hotplug magic ("Start gpsd automatically").
+It will be installed in your HTTP document directory. The first time
+it's invoked, it will generate a file called 'gpsd_config.inc' in that
+directory containing configuration information; edit to taste.  Note
+that for the Google Maps feature work you need to set a valid Google
+API key in gpsd_config.inc.
 
-10. Note for people using gpsd as time source for ntpd: In case you're
+4. Note for people using gpsd as time source for ntpd: In case you're
 using dhcp3-client to configure your system, make sure you disable
 /etc/dhcp3/dhclient-exit-hooks.d/ntp, as dhclient would restart
 ntpd with an automatically created ntp.conf otherwise - and gpsd