update docs for gui "s" scripts

myk002 · myk002 · commit ac7d52514bc7 · 2022-09-06T22:10:40.000-07:00
and turn gui/stockpiles into a gui script instead of a commandline
interface
diff --git a/docs/gui/settings-manager.rst b/docs/gui/settings-manager.rst
@@ -1,10 +1,19 @@
-
 gui/settings-manager
 ====================
 
 .. dfhack-tool::
-    :summary: todo.
+    :summary: Dynamically adjust global DF settings.
     :tags: dfhack
 
+This tool is an in-game editor for settings defined in
+:file:`data/init/init.txt` and :file:`data/init/d_init.txt`. Changes are written
+back to the init files so they will be loaded the next time you start DF. For
+settings that can be dynamically adjusted, such as the population cap, the
+active value used by the game is updated immediately.
+
+Usage
+-----
+
+::
 
-An in-game manager for settings defined in ``init.txt`` and ``d_init.txt``.
+    gui/settings-manager
diff --git a/docs/gui/siege-engine.rst b/docs/gui/siege-engine.rst
@@ -1,39 +1,46 @@
-
 gui/siege-engine
 ================
 
 .. dfhack-tool::
-    :summary: todo.
+    :summary: Extend the functionality and usability of siege engines.
     :tags: fort gameplay buildings
 
+This tool is an in-game interface for `siege-engine`, which allows you to link
+siege engines to stockpiles, restrict operation to certain dwarves, fire a
+greater variety of ammo, and aim in 3 dimensions.
 
-Activate an in-game interface for `siege-engine`, after selecting
-a siege engine in :kbd:`q` mode.
+Run the UI after selecting a siege engine in :kbd:`q` mode.
 
-.. image:: /docs/images/siege-engine.png
+The main UI mode displays the current target, selected ammo item type, linked
+stockpiles and the allowed operator skill range. The map tile color is changed
+to signify if it can be hit by the selected engine: green for fully reachable,
+blue for out of range, red for blocked, yellow for partially blocked.
 
-The main mode displays the current target, selected ammo item
-type, linked stockpiles and the allowed operator skill range. The
-map tile color is changed to signify if it can be hit by the
-selected engine: green for fully reachable, blue for out of
-range, red for blocked, yellow for partially blocked.
-
-Pressing :kbd:`r` changes into the target selection mode, which
-works by highlighting two points with :kbd:`Enter` like all
-designations. When a target area is set, the engine projectiles
-are aimed at that area, or units within it (this doesn't actually
-change the original aiming code, instead the projectile
+Pressing :kbd:`r` changes into the target selection mode, which works by
+highlighting two points with :kbd:`Enter` like all designations. When a target
+area is set, the engine projectiles are aimed at that area, or units within it
+(this doesn't actually change the original aiming code, instead the projectile
 trajectory parameters are rewritten as soon as it appears).
 
-After setting the target in this way for one engine, you can
-'paste' the same area into others just by pressing :kbd:`p` in
-the main page of this script. The area to paste is kept until you
-quit DF, or select another area manually.
+After setting the target in this way for one engine, you can 'paste' the same
+area into others just by pressing :kbd:`p` in the main page of the UI. The area
+to paste is kept until you quit DF, or until you select another area manually.
+
+Pressing :kbd:`t` switches to a mode for selecting a stockpile to take ammo
+from.
+
+Exiting from the siege engine UI via :kbd:`Esc` reverts the view to the state
+prior to starting the script. :kbd:`Shift`:kbd:`Esc` retains the current
+viewport, and also exits from the :kbd:`q` mode to the main map.
 
-Pressing :kbd:`t` switches to a mode for selecting a stockpile to
-take ammo from.
+Usage
+-----
 
-Exiting from the siege engine script via :kbd:`Esc` reverts the
-view to the state prior to starting the script.
-:kbd:`Shift`:kbd:`Esc` retains the current viewport, and also
-exits from the :kbd:`q` mode to main menu.
+::
+
+    gui/siege-engine
+
+Screenshot
+----------
+
+.. image:: /docs/images/siege-engine.png
diff --git a/docs/gui/stamper.rst b/docs/gui/stamper.rst
@@ -1,11 +1,18 @@
-
 gui/stamper
 ===========
 
 .. dfhack-tool::
-    :summary: todo.
+    :summary: Copy, paste, and transform dig designations.
     :tags: fort design map
 
+This tool allows you to copy and paste blocks of dig designations. You can also
+transform what you have copied by shifting it, reflecting it, rotating it,
+and/or inverting it. Designations can also be used as brushes to erase other
+designations and cancel constructions.
+
+Usage
+-----
+
+::
 
-allows manipulation of designations by transforms such as translations, reflections, rotations, and inversion.
-designations can also be used as brushes to erase other designations and cancel constructions.
+    gui/stamper
diff --git a/docs/gui/stockpiles.rst b/docs/gui/stockpiles.rst
@@ -1,21 +1,22 @@
-
 gui/stockpiles
 ==============
 
 .. dfhack-tool::
-    :summary: todo.
+    :summary: Import and export stockpile settings.
     :tags: fort design stockpiles
 
+With a stockpile selected in :kbd:`q` mode, you can use this tool to load
+stockpile settings from a file or save them to a file for later loading, in
+this fort or any other.
+
+Saved stockpile configs are stored in the :file:`stocksettings` subfolder in
+the DF folder.
 
-An in-game interface for `stocksettings`, to
-load and save stockpile settings from the :kbd:`q` menu.
+See `stockpiles` for a commandline interface.
 
-Usage:
+Usage
+-----
 
-:gui/stockpiles -save:         to save the current stockpile
-:gui/stockpiles -load:         to load settings into the current stockpile
-:gui/stockpiles -dir <path>:   set the default directory to save settings into
-:gui/stockpiles -help:         to see this message
+::
 
-Don't forget to ``enable stockpiles`` and create the ``stocksettings`` directory in
-the DF folder before trying to use the GUI.
+    gui/stockpiles
diff --git a/gui/stockpiles.lua b/gui/stockpiles.lua
@@ -19,10 +19,6 @@ the DF folder before trying to use the GUI.
 ]====]
 local stock = require 'plugins.stockpiles'
 
-function check_enabled()
-    return stock.isEnabled()
-end
-
 function world_guard()
     if not dfhack.isMapLoaded() then
         qerror("World is not loaded")
@@ -57,9 +53,7 @@ function usage()
     print("")
 end
 
-if not check_enabled() then
-    qerror("Stockpiles plugin not enabled. Enable it with: enable stockpiles")
-elseif args.load then
+if args.load then
     if not guard() then return end
     stock.load_settings()
 elseif args.save then
@@ -70,5 +64,7 @@ elseif args.dir then
     if not world_guard() then return end
     stock.set_path(args.dir)
 else
-    usage()
+    if not guard() then return end
+    local sp = dfhack.gui.getSelectedBuilding(true)
+    stock.manage_settings(sp)
 end
