Tweak documentation for utils.make_sort_order and devel/prepare-save

LUA_API.rst

@@ -1428,7 +1428,7 @@ utils
 
 * ``utils.make_sort_order(data, ordering)``
 
-  Computes an ordering of objects in data, as a table of integer
+  Computes a sorted permutation of objects in data, as a table of integer
   indices into the data sequence. Uses ``data.n`` as input length
   if present.
 
@@ -1436,7 +1436,7 @@ utils
   as lua tables with following possible fields:
 
   ord.key = *function(value)*
-    Computes comparison key from a data value. Not called on nil.
+    Computes comparison key from input data value. Not called on nil.
     If omitted, the comparison key is the value itself.
   ord.key_table = *function(data)*
     Computes a key table from the data table in one go.
@@ -1448,6 +1448,18 @@ utils
   ord.reverse = *true/false*
     If true, sort non-nil keys in descending order.
 
+  For every comparison during sorting the specs are applied in
+  order until an unambiguous decision is reached. Sorting is stable.
+
+  Example of sorting a sequence by field foo::
+
+    local spec = { key = function(v) return v.foo end }
+    local order = utils.make_sort_order(data, { spec })
+    local output = {}
+    for i = 1,#order do output[i] = data[order[i]] end
+
+  Separating the actual reordering of the sequence in this
+  way enables applying the same permutation to multiple arrays.
   This function is used by the sort plugin.
 
 * ``utils.assign(tgt, src)``

Lua API.html

@@ -1571,14 +1571,14 @@ Returns <em>nil</em> if any of obj or indices is <em>nil</em>, or a numeric inde
 <p>Returns a lua sequence of numbers in start..end.</p>
 </li>
 <li><p class="first"><tt class="docutils literal">utils.make_sort_order(data, ordering)</tt></p>
-<p>Computes an ordering of objects in data, as a table of integer
+<p>Computes a sorted permutation of objects in data, as a table of integer
 indices into the data sequence. Uses <tt class="docutils literal">data.n</tt> as input length
 if present.</p>
 <p>The ordering argument is a sequence of ordering specs, represented
 as lua tables with following possible fields:</p>
 <dl class="docutils">
 <dt>ord.key = <em>function(value)</em></dt>
-<dd><p class="first last">Computes comparison key from a data value. Not called on nil.
+<dd><p class="first last">Computes comparison key from input data value. Not called on nil.
 If omitted, the comparison key is the value itself.</p>
 </dd>
 <dt>ord.key_table = <em>function(data)</em></dt>
@@ -1595,7 +1595,18 @@ Called on non-nil keys; nil sorts last.</p>
 <dd><p class="first last">If true, sort non-nil keys in descending order.</p>
 </dd>
 </dl>
-<p>This function is used by the sort plugin.</p>
+<p>For every comparison during sorting the specs are applied in
+order until an unambiguous decision is reached. Sorting is stable.</p>
+<p>Example of sorting a sequence by field foo:</p>
+<pre class="literal-block">
+local spec = { key = function(v) return v.foo end }
+local order = utils.make_sort_order(data, { spec })
+local output = {}
+for i = 1,#order do output[i] = data[order[i]] end
+</pre>
+<p>Separating the actual reordering of the sequence in this
+way enables applying the same permutation to multiple arrays.
+This function is used by the sort plugin.</p>
 </li>
 <li><p class="first"><tt class="docutils literal">utils.assign(tgt, src)</tt></p>
 <p>Does a recursive assignment of src into tgt.
@@ -1728,6 +1739,8 @@ calls lua code to perform the actual ordering of list items.</p>
 are automatically used by the DFHack core as commands. The
 matching command name consists of the name of the file sans
 the extension.</p>
+<p>If the first line of the script is a one-line comment, it is
+used by the built-in <tt class="docutils literal">ls</tt> and <tt class="docutils literal">help</tt> commands.</p>
 <p><strong>NOTE:</strong> Scripts placed in subdirectories still can be accessed, but
 do not clutter the <tt class="docutils literal">ls</tt> command list; thus it is preferred
 for obscure developer-oriented scripts and scripts used by tools.

scripts/devel/prepare-save.lua

@@ -1,7 +1,22 @@
 -- Prepare the current save for use with devel/find-offsets.
 
+local utils = require 'utils'
+
 df.global.pause_state = true
 
+print[[
+WARNING: THIS SCRIPT IS STRICTLY FOR DFHACK DEVELOPERS.
+
+This script prepares the current savegame to be used
+with devel/find-offsets. It CHANGES THE GAME STATE
+to predefined values, and initiates an immediate
+quicksave, thus PERMANENTLY MODIFYING the save.
+]]
+
+if not utils.prompt_yes_no('Proceed?') then
+    return
+end
+
 --[[print('Placing anchor...')
 
 do