Clarify the device-list commands.

1 files changed, 27 insertions, 23 deletions

diff --git a/gpsd.xml b/gpsd.xml
index fe02b484..647bb191 100644
--- a/gpsd.xml
+++ b/gpsd.xml
@@ -67,7 +67,10 @@ See <xref linkend='accuracy'/> for discussion.</para>
 <varlistentry>
 <term>-F</term>
 <listitem>
-<para>Create a control socket for device addition and removal commands.</para>
+<para>Create a control socket for device addition and removal
+commands.  You must specify a valid pathname on your local filesystem; 
+this will be created as a Unix-domain socket to which you can write
+commands that edit the daemon's internal device list.</para>
 </listitem>
 </varlistentry>
 <varlistentry>
@@ -127,11 +130,12 @@ to standard error.</para>
 </varlistentry>
 </variablelist>
 
-<para>At any given time, each client will be listening to only one of
-the GPSes known to the daemon.  By default, a client's device is the
-one that most recently shipped information to the daemon at the time
-the client first requests GPS information (that is, issues any comand
-other than F, K, W=0 or R=0).</para>
+<para>Internally, the daemon maintains a device list holding the
+pathnames of GPSes known to the daemon. At any given time, each client
+will be listening to only one of these.  By default, a client's device
+is the one that most recently shipped information to the daemon at the
+time the client first requests GPS information (that is, issues any
+comand other than F, K, W=0 or R=0).</para>
 
 <para>The request protocol for <application>gpsd</application> clients
 is very simple.  Each request normally consists of a single ASCII
@@ -189,25 +193,25 @@ See also the 'q' command.</para>
 <varlistentry>
 <term>f</term>
 <listitem><para>Gets or sets the active GPS device name. The bare
-command 'f' requests a response containing 'f=' followed by the name
-of the active GPS device.  The command may be followed by an '=', in
+command 'f' requests a response containing 'F=' followed by the name
+of the active GPS device.  The other form of the command is 'f=', in
 which case all following printable characters up to but not including
 the next CR/LF are interpreted as the name of a trial GPS device. If
 the trial device is in <application>gpsd</application>'s device list,
 it is opened and read to see if a GPS can be found there.  If it can,
 the trial device becomes the active device for this client.</para>
 
-<para>The 'F=' command may fail if the specified device name is not on the
-daemon's internal search list.  This search list is initialized with
-the path given in the -f command-line
-option, if that was specified.  For security reasons, ordinary clients
-cannot change this search list; instead, this must be done via the
-daemon's local control socket declared with the -F option.</para>
+<para>The 'f=' command may fail if the specified device name is not on
+the daemon's device list.  This device list is initialized with the
+path given in the -f command-line option, if that was specified.  For
+security reasons, ordinary clients cannot change this device list;
+instead, this must be done via the daemon's local control socket
+declared with the -F option.</para>
 
-<para>Once an 'F=' command succeeds, the client is tied to the
+<para>Once an 'f=' command succeeds, the client is tied to the
 specified device until the client disconnects.</para>
 
-<para>Whether the command is 'F' or 'F=' or not, and whether it succeeds
+<para>Whether the command is 'f' or 'f=' or not, and whether it succeeds
 or not, the response always lists the name of the client's device.</para>
 
 <para>(At protocol level 1, the F command failed if more than one
@@ -487,13 +491,13 @@ in.  When it is properly installed along with hotplug notifier
 scripts feeding it device-add commands, <application>gpsd</application> 
 should require no configuration or user action to find devices.</para>
 
-<para>The commands to add and remove GPS device paths from the
-daemon's internal search list cannot be sent over the socket from a
-client.  Instead, they must be written to a local Unix-domain socket
-which will be accessible only to programs running as root.  This
-control socket will be located wherever the -F option specifies it; if
-that option was not given at startup, <application>gpsd</application>
-is restricted to monitoring its default device.</para>
+<para><application>gpsd</application> maintains an internal list of
+GPS devices.  If you specify an -f option, the list is initialized
+with that pathname as its only member; otherwuse the list starts
+empty.  Commands to add and remove GPS device paths from the daemon's
+device list must be written to a local Unix-domain socket which will
+be accessible only to programs running as root.  This control socket
+will be located wherever the -F option specifies it.</para>
 
 <para>To point <application>gpsd</application> at a device that may be
 a GPS, write to the control socket a plus sign ('+') followed by the