Remove historical information about the runlevel variable and just

mention it in a footnote. Use a real example of the dependencies
variable from smb-os-discovery.

docs/scripting.xml

@@ -880,45 +880,35 @@ that.</para>
       <indexterm><primary sortas="dependencies script variable">&ldquo;<varname>dependencies</varname>&rdquo; script variable</primary></indexterm>
       <indexterm><primary>script dependencies</primary></indexterm>
        <para>
-         In earlier versions of NSE, script authors were able to specify a
-         <literal>runlevel</literal> that would specify the execution order of
-         the scripts NSE will run. Scripts that had a smaller runlevel would
-         run before scripts with a larger runlevel. Scripts with an equal
-         runlevel would run concurrently. This method of describing an ordered
-         execution has been replaced by <literal>dependencies</literal>.
-         Dependencies specify other discrete scripts that the script depends on
-         for its execution. A script may need to depend on another script for
-         many reasons. For example, many scripts may rely on authentication
-         credentials discovered by brute-forcing scripts. 
+        The <literal>dependencies</literal> field is an array containing the
+        names of scripts that should run before this script. This is used when
+        one script can make use of the results of another. For example, most of
+        the <filename>smb-*</filename> scripts depend on
+        <filename>smb-brute</filename>,<indexterm><primary><filename>smb-brute.nse</filename></primary></indexterm>
+        because the accounts found by <filename>smb-brute</filename> may allow
+        the other scripts to get more information.
        </para>
        <para>
-         Scripts may specify an array of script names that the script depends
-         on.  When we say "depends on", we mean it in a loose sense. That is, a
+         When we say <quote>depend on</quote>, we mean it in a loose sense. That is, a
          script will still run despite missing dependencies.  Given the
          dependencies, the script will run after all the scripts listed in the
-         dependencies array. We may specify a dependencies array like so:
+         dependencies array. This is an example of the
+         <literal>dependencies</literal> table from
+         <filename>smb-os-discovery</filename>:<indexterm><primary><filename>smb-os-discovery.nse</filename></primary></indexterm>
 <programlisting>
-dependencies = {"script1", "script2"}
+dependencies = {"smb-brute"}
 </programlisting>
-       </para>
-       <para>
-         The dependencies table is an optional script field. NSE will assume
+         The dependencies table is optional. NSE will assume
          the script has no dependencies if the field is omitted.
        </para>
        <para>
-         Dependencies offer many advantages over runlevels. First, and
-         obviously, scripts can now specify each script they depend on without
-         worrying about specifying an arbitrary number that is greater than
-         scripts it depends on. Second, scripts no longer limit NSE's ability
-         to intelligently schedule scripts to maximize parallelism. Having
-         unique runlevels would force NSE to schedule the scripts to execute
-         serially.
-       </para>
-       <para>
-         Runlevels are still used as an internal representation of the order of
-         scripts that are automatically generated by the dependencies. When
-         running your scripts you will see each runlevel (and the number of
-         runlevels) grouping of scripts run in NSE's output:
+         Dependencies establish an internal ordering of scripts, assigning each
+         one a number called a <quote>runlevel</quote><footnote><para>Up through
+         Nmap version 5.10BETA2, dependencies didn't exist and script authors
+         had to set a <varname>runlevel</varname> field manually.</para></footnote>.<indexterm><primary>runlevel</primary></indexterm>
+         When
+         running your scripts you will see the runlevel (along with the total number of
+         runlevels) of each grouping of scripts run in NSE's output:
 <screen>
 NSE: Script scanning 127.0.0.1.
 NSE: Starting runlevel 1 (of 3) scan.
@@ -1834,11 +1824,9 @@ try(socket:send(result))
 	information to completely different scripts.  For example,
 	the <literal>snmp-brute</literal> script saves a discovered
 	community name in the registry where it may be used by other
-	SNMP scripts.  Scripts which leave information behind for a
-	second script must have a lower <literal>runlevel</literal>
-	than that second script, or there is no guarantee that they
-	will run first.<indexterm><primary>run level of
-	scripts</primary></indexterm>
+	SNMP scripts.  Script which use the results of another script
+        must declare it using the <literal>dependencies</literal>
+        variable to make sure that the earlier script runs first.
         </para>
 
         <para>Because every script can write to the registry table, it
@@ -1891,7 +1879,7 @@ try(socket:send(result))
 
       The head of the script is essentially its meta information. This
       includes the
-      fields: <literal>description</literal>, <literal>categories</literal>, <literal>runlevel</literal>, <literal>author</literal>, and <literal>license</literal> as well as
+      fields: <literal>description</literal>, <literal>categories</literal>, <literal>dependencies</literal>, <literal>author</literal>, and <literal>license</literal> as well as
       initial NSEDoc information such as usage, args, and output
       tags (see <xref linkend="nsedoc"/>).
       </para>
@@ -2683,9 +2671,10 @@ and <literal>open|filtered</literal><indexterm><primary><literal>open|filtered</
 port on the hosts.  The combination can grow quite large, so portrules should be kept as simple as possible.  Save any heavy computation for the script's <literal>action</literal>.</para>
 
 <para>Next, a Lua thread is created for each of the matching script-target combinations.  Each thread
-is stored with pertinent information such as the runlevel, target, target port (if applicable), host and port tables
+is stored with pertinent information such as its dependencies, target, target port (if applicable), host and port tables
 (passed to the <literal>action</literal>), and the script type (service or host script).
-The <function>mainloop</function> function then processes each runlevel grouping of threads in order.
+The <function>mainloop</function> function then processes each runlevel<indexterm><primary>runlevel</primary></indexterm>
+grouping of threads in order.
 </para>
 
     </sect2>