[PATCH] wpa_supplicant man page: clearly state which options are given per interface.

[Pavel Polischouk]

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.

diff --git a/wpa_supplicant/doc/docbook/wpa_supplicant.sgml b/wpa_supplicant/doc/docbook/wpa_supplicant.sgml
index de3409d..84f5990 100644
--- a/wpa_supplicant/doc/docbook/wpa_supplicant.sgml
+++ b/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>