Updated refguide and scripting chapter of book to the new syntax of the

--script-args as well as a more full account of some details. The previous text
was very vague about some features, especially array values.

docs/refguide.xml

@@ -2174,25 +2174,27 @@ which lists the category or categories in which each script belongs.</para>
 </varlistentry>
       
 	  <varlistentry>
-        <term><option>--script-args <replaceable>name1</replaceable>=<replaceable>value1</replaceable>,<replaceable>name2</replaceable>={<replaceable>name3</replaceable>=<replaceable>value3</replaceable>},<replaceable>name4</replaceable>=<replaceable>value4</replaceable></option>
+        <term><option>--script-args <replaceable>name1</replaceable>=<replaceable>value1</replaceable>,<replaceable>name2</replaceable>={<replaceable>name3</replaceable>=<replaceable>value3</replaceable>,<replaceable>array_value1</replaceable>},<replaceable>name4</replaceable>=<replaceable>value4</replaceable>,<replaceable>array_value2</replaceable></option>
         <indexterm significance="preferred"><primary><option>--script-args</option></primary></indexterm>
         <indexterm><primary>script arguments</primary><seealso><option>--script-args</option></seealso></indexterm></term>
 
 <listitem>
-<para>Lets you provide arguments to NSE scripts. Arguments are passed
-as <literal>name=value</literal> pairs. The provided argument is
-processed and stored inside a Lua table, to which all scripts have
-access. The names are taken as strings (which must be alphanumeric
-values) and used as keys inside the
-<literal>argument-table</literal>. Values are either strings or tables
-themselves (surrounded by &lsquo;<literal>{</literal>&rsquo; and
-&lsquo;<literal>}</literal>&rsquo;).
-For example, you could pass the comma-separated arguments:
-<literal>user=bar,pass=foo,whois={whodb=nofollow+ripe}</literal>.
-String arguments are potentially used by several scripts; subtables are
-normally used by only one script. In scripts that take a subtable, the
-subtable is usually named after the script (like
-<literal>whois</literal> in this example).</para>
+<para>
+Lets you provide arguments to NSE scripts. Arguments are a comma separated list
+of <literal>name=value</literal> pairs or array values within a table.  Array
+values are simply values with implicit ordered numeric keys. Array Values as
+well as Keys and Values in key-value pairs may be strings of characters not
+including <literal>"{", "}", "=", ","<literal> or whitespace.  You may quote
+these strings to allow all characters.  The quote delimiter must be escaped by
+a backslash if used inside the quoted string. A backslash is only used as an
+escape mechanism for quote delimiters in quoted strings; in all other contexts
+it is interpreted literally. Array Values and Values in key-value pairs are
+allowed to be nested tables delimited by <literal>{</literal> and
+<literal>}</literal>.  An example of script arguments: <literal>--script-args
+auth={user=foo,pass=',{}=bar'},userdb=C:\Path\To\File</literal>.  See NSE's
+online script documentation at http://nmap.org/nsedoc for each script's
+accepted arguments.
+</para>
 </listitem>
 
 </varlistentry>

docs/scripting.xml

@@ -701,24 +701,45 @@ Nmap script database.</para>
       <indexterm><primary>script arguments</primary></indexterm>
       <para>
       Arguments may be passed to NSE scripts using the
-	  <option>--script-args</option> option. The script arguments are generally
-	  name-value pairs. They are provided to scripts as a Lua table named
-	  <literal>args</literal> inside <literal><link
-	  linkend="nse-api-registry">nmap.registry</link></literal>.
-	  The argument names are keys for the corresponding values. The values can be
-	  either strings or tables. Subtables can be used to pass arguments to 
-	  scripts with finer granularity, such as passing different usernames for
-	  different scripts. Here is a typical Nmap invocation with script arguments:
-	  </para>
+      <option>--script-args</option> option. The arguments describe a table of
+      key-value pairs and possibly array values. Array values in this case have
+      omitted numerical keys.  The arguments are provided to scripts as a Lua
+      table named <literal>args</literal> inside <literal><link
+      linkend="nse-api-registry">nmap.registry</link></literal>.
+      </para>
+      <para>
+      Similar to Lua table constructor syntax, we delimit key-value pairs and
+      array values by commas. A key-value pair is separated by an equal sign.
+      Each successive array value is accessed by implicit integer keys,
+      starting from 1.  Array values do not necessarily need to appear after
+      all key-value pairs or in succession. They are typically used to
+      enumerate a list of items, such as proxy hosts or usernames.
+      </para>
+      <para>
+      A point of divergence is the acceptance of (possibly unquoted) strings
+      containing many illegal characters.  A key, value, or an array value may
+      be a sequence of characters not including <literal>'{', '}', ',',
+      '='</literal> or whitespace. You may overcome this restriction by using
+      quotes (single or double) to allow all characters within the quotation
+      marks.  Naturally, the quote delimiter cannot appear within your quoted
+      string unless you escape the quote using a backslash. A backslash is only
+      used to escape quotation marks in this special case; in all other cases a
+      backslash is interpreted literally.  A value in a key-value pair or an
+      array value may also be a nested table delimited by, as in Lua,
+      <literal>'{' and '}'</literal>.  Note that nested subtables are commonly
+      used to pass arguments to scripts with finer granularity, such as passing
+      different usernames for different scripts.
+      </para>
+      <para>Here is a typical Nmap invocation with script arguments: </para>
 	  <para>
 <indexterm><primary><option>--script-args</option></primary><secondary>example of</secondary></indexterm>
-<command>nmap -sC --script-args user=foo,pass=bar,whois={whodb=nofollow+ripe}</command>
+<command>nmap -sC --script-args user=foo,pass=',{}=bar',whois={whodb=nofollow+ripe},userdb=C:\Some\Path\To\File</command>
 	  </para>
 	  <para>
 	  The aforementioned command results in this Lua table:
           </para>
 <programlisting>
-{user="foo",pass="bar",whois={whodb="nofollow+ripe"}}
+{user="foo",pass=",{}=bar",whois={whodb="nofollow+ripe"},userdb="C:\\Some\\Path\\To\\File"}
 </programlisting>
  
 	  <para>You could therefore access the username (<literal>foo</literal>)