man wpa_supplicant: Clearly state which options are given per interface

Documentation appeared a little vague about which options are global and
which are tied to a particular interface. This leads to confusion when
using certain combinations of options, e.g. the command "wpa_supplicant
-c /etc/wpa_supplican.conf -u" will not do what is intuitively expected
from it - it will not read the config file given with -c option because
no -i option was given. This command is still valid because -u option is
used. The wpa_supplicant running like this will also not listen on any
control socket, because the socket file name is usually given in the
config file. This command line also happens to be the default in Fedora 9.
This patch does not try to change any behaviour, but rather document
these nuances clearly.

wpa_supplicant/doc/docbook/wpa_supplicant.sgml

@@ -327,11 +327,15 @@
 
   <refsect1>
     <title>Command Line Options</title>
+    <para>Most command line options have global scope. Some are given per
+    interface, and are only valid if at least one <option>-i</option> option
+    is specified, otherwise they're ignored. Option groups for different
+    interfaces must be separated by <option>-N</option> option.</para>
     <variablelist>
       <varlistentry>
 	<term>-b br_ifname</term>
 	<listitem>
-	  <para>Optional bridge interface name.</para>
+	  <para>Optional bridge interface name. (Per interface)</para>
 	</listitem>
       </varlistentry>
 
@@ -345,35 +349,40 @@
       <varlistentry>
 	<term>-c filename</term>
 	<listitem>
-	  <para>Path to configuration file.</para>
+	  <para>Path to configuration file. (Per interface)</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>-C ctrl_interface</term>
 	<listitem>
-	  <para>Path to ctrl_interface socket (only used if -c is not).</para>
+	  <para>Path to ctrl_interface socket (Per interface. Only used if
+		  <option>-c</option> is not).</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>-i ifname</term>
 	<listitem>
-	  <para>Interface to listen on.</para>
+	  <para>Interface to listen on. Multiple instances of this option can
+	  be present, one per interface, separated by <option>-N</option>
+	  option (see below).</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>-d</term>
 	<listitem>
-	  <para>Increase debugging verbosity (-dd even more).</para>
+	  <para>Increase debugging verbosity (<option>-dd</option> even
+		  more).</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>-D driver</term>
 	<listitem>
-	  <para>Driver to use.  See the available options below.</para>
+	  <para>Driver to use. (Per interface, see the available options
+		  below.)</para>
 	</listitem>
       </varlistentry>
 
@@ -387,7 +396,8 @@
       <varlistentry>
 	<term>-g global ctrl_interface</term>
 	<listitem>
-	  <para>Path to global ctrl_interface socket.</para>
+	  <para>Path to global ctrl_interface socket. If specified, interface
+	  definitions may be omitted.</para>
 	</listitem>
       </varlistentry>
 
@@ -422,7 +432,7 @@
       <varlistentry>
 	<term>-p</term>
 	<listitem>
-	  <para>Driver parameters.</para>
+	  <para>Driver parameters. (Per interface)</para>
 	</listitem>
       </varlistentry>
 
@@ -436,14 +446,16 @@
       <varlistentry>
 	<term>-q</term>
 	<listitem>
-	  <para>Decrease debugging verbosity (-qq even less).</para>
+	  <para>Decrease debugging verbosity (<option>-qq</option> even
+		  less).</para>
 	</listitem>
       </varlistentry>
 
       <varlistentry>
 	<term>-u</term>
 	<listitem>
-	  <para>Enabled DBus control interface.</para>
+	  <para>Enabled DBus control interface. If enabled, interface
+	  definitions may be omitted.</para>
 	</listitem>
       </varlistentry>