Migrate fix, gui script docs; add link shortcuts

Because it's a lot easier to link to bug reports this way. The migration is mostly just a copy-paste job, but I'm using keybinding styles where appropriate too.
2015-10-24 01:37:39 +11:00 · 2015-10-24 01:37:39 +11:00 · f8d965b8ea
parent 5e02e00e2c
commit f8d965b8ea
38 changed files with 510 additions and 453 deletions
--- a/docs/Scripts.rst
+++ b/docs/Scripts.rst
@ -69,443 +69,6 @@ The following pages document all the standard DFHack scripts.
   /scripts/3rdparty/*/*
 fix/blood-del
 =============
 Makes it so that future caravans won't bring barrels full of blood, ichor, or goo.
 fix/build-location
 ==================
 Fixes construction jobs that are stuck trying to build a wall while standing
 on the same exact tile (bug 5991), designates the tile restricted traffic to
 hopefully avoid jamming it again, and unsuspends them.
 fix/dead-units
 ==============
 Removes uninteresting dead units from the unit list. Doesn't seem to give any
 noticeable performance gain, but migrants normally stop if the unit list grows
 to around 3000 units, and this script reduces it back.
 fix/fat-dwarves
 ===============
 Avoids 5-10% FPS loss due to constant recalculation of insulation for dwarves at
 maximum fatness, by reducing the cap from 1,000,000 to 999,999.
 fix/feeding-timers
 ==================
 Reset the GiveWater and GiveFood timers of all units as appropriate.
 fix/growth-bug
 ==============
 Fixes locally born units such that they will grow larger than their birth size.
 Note that this bug was fixed in DF version 0.40.02.
 fix/item-occupancy
 ==================
 Diagnoses and fixes issues with nonexistant 'items occupying site', usually
 caused by autodump bugs or other hacking mishaps.
 fix/loyaltycascade
 ==================
 Aborts loyalty cascades by fixing units whose own civ is the enemy.
 fix/population-cap
 ==================
 Run this after every migrant wave to ensure your population cap is not exceeded.
 The issue with the cap is that it is compared to the population number reported
 by the last caravan, so once it drops below the cap, migrants continue to come
 until that number is updated again.
 fix/stable-temp
 ===============
 Instantly sets the temperature of all free-lying items to be in equilibrium with
 the environment and stops temperature updates. In order to maintain this efficient
 state however, use `tweak` ``stable-temp`` and `tweak` ``fast-heat``.
 fix/stuckdoors
 ==============
 Fix doors that are stuck open due to incorrect map occupancy flags, eg due to
 incorrect use of teleport.
 .. _gui/advfort:
 gui/advfort
 ===========
 This script allows to perform jobs in adventure mode. For more complete help
 press '?' while script is running. It's most comfortable to use this as a
 keybinding. (e.g. keybinding set Ctrl-T gui/advfort). Possible arguments:
 * -a or --nodfassign - uses different method to assign items.
 * -i or --inventory - checks inventory for possible items to use in the job.
 * -c or --cheat - relaxes item requirements for buildings (e.g. walls from bones).
  implies -a
 * job - selects that job (e.g. Dig or FellTree)
 An example of player digging in adventure mode:
 .. image:: images/advfort.png
 .. admonition:: DISCLAIMER
    advfort changes only persist in non procedural sites. Namely: player forts, caves, camps.
 gui/advfort_items
 =================
 Does something with items in adventure mode jobs.
 .. _gui/assign-rack:
 gui/assign-rack
 ===============
 `This script requires a binpatch <binpatches/needs-patch>`, which has not
 been available since DF 0.34.11
 gui/autobutcher
 ===============
 An in-game interface for `autobutcher`.
 gui/choose-weapons
 ==================
 Bind to a key (the example config uses Ctrl-W), and activate in the Equip->View/Customize
 page of the military screen.
 Depending on the cursor location, it rewrites all 'individual choice weapon' entries
 in the selected squad or position to use a specific weapon type matching the assigned
 unit's top skill. If the cursor is in the rightmost list over a weapon entry, it rewrites
 only that entry, and does it even if it is not 'individual choice'.
 Rationale: individual choice seems to be unreliable when there is a weapon shortage,
 and may lead to inappropriate weapons being selected.
 gui/clone-uniform
 =================
 Bind to a key (the example config uses Ctrl-C), and activate in the Uniforms
 page of the military screen with the cursor in the leftmost list.
 When invoked, the script duplicates the currently selected uniform template,
 and selects the newly created copy.
 .. _gui/companion-order:
 gui/companion-order
 ===================
 A script to issue orders for companions. Select companions with lower case chars, issue orders with upper
 case. Must be in look or talk mode to issue command on tile.
 .. image:: images/companion-order.png
 * move - orders selected companions to move to location. If companions are following they will move no more than 3 tiles from you.
 * equip - try to equip items on the ground.
 * pick-up - try to take items into hand (also wield)
 * unequip - remove and drop equipment
 * unwield - drop held items
 * wait - temporarily remove from party
 * follow - rejoin the party after "wait"
 * leave - remove from party (can be rejoined by talking)
 .. _gui/create-item:
 gui/create-item
 ===============
 A graphical interface for creating items.
 gui/dfstatus
 ============
 Show a quick overview of critical stock quantities, including food, drinks, wood, and various bars.
 Sections can be enabled/disabled/configured by editing ``dfhack-config/dfstatus.lua``.
 .. _gui/gm-editor:
 gui/gm-editor
 =============
 There are three ways to open this editor:
 * using gui/gm-editor command/keybinding - opens editor on what is selected
  or viewed (e.g. unit/item description screen)
 * using gui/gm-editor <lua command> - executes lua command and opens editor on
  its results (e.g. gui/gm-editor "df.global.world.items.all" shows all items)
 * using gui/gm-editor dialog - shows an in game dialog to input lua command. Works
  the same as version above.
 .. image:: images/gm-editor.png
 This editor allows to change and modify almost anything in df. Press '?' for an
 in-game help.
 gui/gm-unit
 ===========
 An editor for various unit attributes.
 gui/guide-path
 ==============
 Bind to a key (the example config uses Alt-P), and activate in the Hauling menu with
 the cursor over a Guide order.
 .. image:: images/guide-path.png
 The script displays the cached path that will be used by the order; the game
 computes it when the order is executed for the first time.
 .. _gui/hack-wish:
 gui/hack-wish
 =============
 An alias for `gui/create-item`.  Deprecated.
 gui/hello-world
 ===============
 A basic example for testing, or to start your own script from.
 gui/liquids
 ===========
 To use, bind to a key (the example config uses Alt-L) and activate in the 'k' mode.
 .. image:: images/liquids.png
 This script is a gui front-end to `liquids` and works similarly,
 allowing you to add or remove water & magma, and create obsidian walls & floors.
 .. warning::
    There is **no undo support**.  Bugs in this plugin have been
    known to create pathfinding problems and heat traps.
 The ``b`` key changes how the affected area is selected. The default *Rectangle*
 mode works by selecting two corners like any ordinary designation. The ``p``
 key chooses between adding water, magma, obsidian walls & floors, or just
 tweaking flags.
 When painting liquids, it is possible to select the desired level with ``+-``,
 and choose between setting it exactly, only increasing or only decreasing
 with ``s``.
 In addition, ``f`` allows disabling or enabling the flowing water computations
 for an area, and ``r`` operates on the "permanent flow" property that makes
 rivers power water wheels even when full and technically not flowing.
 After setting up the desired operations using the described keys, use ``Enter`` to apply them.
 gui/mechanisms
 ==============
 To use, bind to a key (the example config uses Ctrl-M) and activate in the 'q' mode.
 .. image:: images/mechanisms.png
 Lists mechanisms connected to the building, and their links. Navigating the list centers
 the view on the relevant linked buildings.
 To exit, press ESC or Enter; ESC recenters on the original building, while Enter leaves
 focus on the current one. Shift-Enter has an effect equivalent to pressing Enter, and then
 re-entering the mechanisms ui.
 gui/mod-manager
 ===============
 A simple way to install and remove small mods.
 It looks for specially formatted mods in df subfolder 'mods'. Mods are not
 included, but some examples are `available here`_.
 .. _`available here`: https://github.com/warmist/df-mini-mods
 .. image:: images/mod-manager.png
 gui/no-dfhack-init
 ==================
 Shows a warning at startup if no valid ``dfhack.init`` file is found.
 .. _gui/power-meter:
 gui/power-meter
 ===============
 An in-game interface for `power-meter`.
 .. _gui/rename:
 gui/rename
 ==========
 Backed by `rename`, this script allows entering the desired name
 via a simple dialog in the game ui.
 * ``gui/rename [building]`` in 'q' mode changes the name of a building.
  .. image:: images/rename-bld.png
  The selected building must be one of stockpile, workshop, furnace, trap, or siege engine.
  It is also possible to rename zones from the 'i' menu.
 * ``gui/rename [unit]`` with a unit selected changes the nickname.
  Unlike the built-in interface, this works even on enemies and animals.
 * ``gui/rename unit-profession`` changes the selected unit's custom profession name.
  .. image:: images/rename-prof.png
  Likewise, this can be applied to any unit, and when used on animals it overrides
  their species string.
 The ``building`` or ``unit`` options are automatically assumed when in relevant ui state.
 The example config binds building/unit rename to Ctrl-Shift-N, and
 unit profession change to Ctrl-Shift-T.
 gui/room-list
 =============
 To use, bind to a key (the example config uses Alt-R) and activate in the 'q' mode,
 either immediately or after opening the assign owner page.
 .. image:: images/room-list.png
 The script lists other rooms owned by the same owner, or by the unit selected in the assign
 list, and allows unassigning them.
 .. _gui/siege-engine:
 gui/siege-engine
 ================
 An in-game interface for `siege-engine`.
 .. _gui/stockpiles:
 gui/stockpiles
 ==============
 An in-game interface for `stocksettings`, to
 load and save stockpile settings from the 'q' menu.
 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/unit-info-viewer
 ====================
 Displays age, birth, maxage, shearing, milking, grazing, egg laying, body size,
 and death info about a unit. Recommended keybinding Alt-I.
 .. _gui/workflow:
 gui/workflow
 ============
 Bind to a key (the example config uses Alt-W), and activate with a job selected
 in a workshop in the 'q' mode.
 .. image:: images/workflow.png
 This script provides a simple interface to constraints managed by `workflow`.
 When active, it displays a list of all constraints applicable to the
 current job, and their current status.
 A constraint specifies a certain range to be compared against either individual
 *item* or whole *stack* count, an item type and optionally a material. When the
 current count is below the lower bound of the range, the job is resumed; if it
 is above or equal to the top bound, it will be suspended. Within the range, the
 specific constraint has no effect on the job; others may still affect it.
 Pressing 'I' switches the current constraint between counting stacks or items.
 Pressing 'R' lets you input the range directly; 'e', 'r', 'd', 'f' adjust the
 bounds by 5, 10, or 20 depending on the direction and the 'I' setting (counting
 items and expanding the range each gives a 2x bonus).
 Pressing 'A' produces a list of possible outputs of this job as guessed by
 workflow, and lets you create a new constraint by choosing one as template. If you
 don't see the choice you want in the list, it likely means you have to adjust
 the job material first using `job` ``item-material`` or `gui/workshop-job`,
 as described in `workflow` documentation. In this manner, this feature
 can be used for troubleshooting jobs that don't match the right constraints.
 .. image:: images/workflow-new1.png
 If you select one of the outputs with Enter, the matching constraint is simply
 added to the list. If you use Shift-Enter, the interface proceeds to the
 next dialog, which allows you to edit the suggested constraint parameters to
 suit your need, and set the item count range.
 .. image:: images/workflow-new2.png
 Pressing 'S' (or, with the example config, Alt-W in the 'z' stocks screen)
 opens the overall status screen, which was copied from the C++ implementation
 by falconne for better integration with the rest of the lua script:
 .. image:: images/workflow-status.png
 This screen shows all currently existing workflow constraints, and allows
 monitoring and/or changing them from one screen. The constraint list can
 be filtered by typing text in the field below.
 The color of the stock level number indicates how "healthy" the stock level
 is, based on current count and trend. Bright green is very good, green is good,
 red is bad, bright red is very bad.
 The limit number is also color-coded. Red means that there are currently no
 workshops producing that item (i.e. no jobs). If it's yellow, that means the
 production has been delayed, possibly due to lack of input materials.
 The chart on the right is a plot of the last 14 days (28 half day plots) worth
 of stock history for the selected item, with the rightmost point representing
 the current stock value. The bright green dashed line is the target
 limit (maximum) and the dark green line is that minus the gap (minimum).
 .. _gui/workshop-job:
 gui/workshop-job
 ================
 Bind to a key (the example config uses Alt-A), and activate with a job selected in
 a workshop in the 'q' mode.
 .. image:: images/workshop-job.png
 The script shows a list of the input reagents of the selected job, and allows changing
 them like the `job` ``item-type`` and `job` ``item-material`` commands.
 Specifically, pressing the 'i' key pops up a dialog that lets you select an item
 type from a list.
 .. image:: images/workshop-job-item.png
 Pressing 'm', unless the item type does not allow a material,
 lets you choose a material.
 .. image:: images/workshop-job-material.png
 Since there are a lot more materials than item types, this dialog is more complex
 and uses a hierarchy of sub-menus. List choices that open a sub-menu are marked
 with an arrow on the left.
 .. warning::
  Due to the way input reagent matching works in DF, you must select an item type
  if you select a material, or the material will be matched incorrectly in some cases.
  If you press 'm' without choosing an item type, the script will auto-choose it
  if there is only one valid choice, or pop up an error message box instead of the
  material selection dialog.
 Note that both materials and item types presented in the dialogs are filtered
 by the job input flags, and even the selected item type for material selection,
 or material for item type selection. Many jobs would let you select only one
 input item type.
 For example, if you choose a *plant* input item type for your prepare meal job,
 it will only let you select cookable materials.
 If you choose a *barrel* item instead (meaning things stored in barrels, like
 drink or milk), it will let you select any material, since in this case the
 material is matched against the barrel itself. Then, if you select, say, iron,
 and then try to change the input item type, now it won't let you select *plant*;
 you have to unset the material first.
 .. _modtools/add-syndrome:
 modtools/add-syndrome
@ -620,9 +183,6 @@ modtools/transform-unit
 Transforms a unit into another unit type, possibly permanently.
 =============
 Other Scripts
 =============
 ban-cooking
 ===========
--- a/docs/conf.py
+++ b/docs/conf.py
@ -100,7 +100,21 @@ document_scripts()
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = ['sphinx.ext.extlinks']
 # This config value must be a dictionary of external sites, mapping unique
 # short alias names to a base URL and a prefix.
 # See http://sphinx-doc.org/ext/extlinks.html
 extlinks = {
    'wiki': ('http://dwarffortresswiki.org/%s', ''),
    'forums': ('http://www.bay12forums.com/smf/index.php?topic=%s',
               'Bay12 forums thread '),
    'dffd': ('http://dffd.bay12games.com/file.php?id=%s', 'DFFD file '),
    'bug': ('http://www.bay12games.com/dwarves/mantisbt/view.php?id=%s',
            'Bug ')
 }
 # some aliases for link directives
 extlinks['forum'] = extlinks['forums']
 # Add any paths that contain templates here, relative to this directory.
 templates_path = []
--- a/scripts/fix/blood-del.lua
+++ b/scripts/fix/blood-del.lua
@ -1,8 +1,13 @@
 --blood-del.lua
 --makes it so that civs won't come with barrels full of blood, ichor, or goo
 --author Urist Da Vinci
 --edited by expwnent, scamtank
 --[[=begin
 fix/blood-del
 =============
 Makes it so that future caravans won't bring barrels full of blood, ichor, or goo.
 =end]]
 local my_entity=df.historical_entity.find(df.global.ui.civ_id)
 local sText=" "
 local k=0
--- a/scripts/fix/build-location.lua
+++ b/scripts/fix/build-location.lua
@ -1,7 +1,15 @@
 -- Lets constructions reconsider the build location.
 -- Partial work-around for http://www.bay12games.com/dwarves/mantisbt/view.php?id=5991
 --[[=begin
 fix/build-location
 ==================
 Fixes construction jobs that are stuck trying to build a wall while standing
 on the same exact tile (:bug:`5991`), designates the tile restricted traffic to
 hopefully avoid jamming it again, and unsuspends them.
 =end]]
 local utils = require('utils')
 local count = 0
--- a/scripts/fix/dead-units.lua
+++ b/scripts/fix/dead-units.lua
@ -1,5 +1,13 @@
 -- Remove uninteresting dead units from the unit list.
 --[[=begin
 fix/dead-units
 ==============
 Removes uninteresting dead units from the unit list. Doesn't seem to give any
 noticeable performance gain, but migrants normally stop if the unit list grows
 to around 3000 units, and this script reduces it back.
 =end]]
 local units = df.global.world.units.active
 local dwarf_race = df.global.ui.race_id
 local dwarf_civ = df.global.ui.civ_id
--- a/scripts/fix/fat-dwarves.lua
+++ b/scripts/fix/fat-dwarves.lua
@ -2,7 +2,14 @@
 --
 -- See for more info:
 --   http://www.bay12games.com/dwarves/mantisbt/view.php?id=5971
 --[[=begin
 fix/fat-dwarves
 ===============
 Avoids 5-10% FPS loss due to constant recalculation of insulation for dwarves at
 maximum fatness, by reducing the cap from 1,000,000 to 999,999.
 =end]]
 local num_fat = 0
 local num_lagging = 0
--- a/scripts/fix/feeding-timers.lua
+++ b/scripts/fix/feeding-timers.lua
@ -2,7 +2,13 @@
 -- original author: tejón
 -- rewritten by expwnent
 -- see repeat.lua for how to run this every so often automatically
 --[[=begin
 fix/feeding-timers
 ==================
 Reset the GiveWater and GiveFood timers of all units as appropriate.
 =end]]
 local args = {...}
 if args[1] ~= nil then
 print("fix/feeding-timers usage")
--- a/scripts/fix/item-occupancy.lua
+++ b/scripts/fix/item-occupancy.lua
@ -1,10 +1,17 @@
 -- Verify item occupancy and block item list integrity.
 --
 -- Checks:
 -- 1) Item has flags.on_ground <=> it is in the correct block item list
 -- 2) A tile has items in block item list <=> it has occupancy.item
 -- 3) The block item lists are sorted.
 --[[=begin
 fix/item-occupancy
 ==================
 Diagnoses and fixes issues with nonexistant 'items occupying site', usually
 caused by `autodump` bugs or other hacking mishaps. Checks that:
 #. Item has ``flags.on_ground`` <=> it is in the correct block item list
 #. A tile has items in block item list <=> it has ``occupancy.item``
 #. The block item lists are sorted
 =end]]
 local utils = require 'utils'
 function check_block_items(fix)
--- a/scripts/fix/loyaltycascade.rb
+++ b/scripts/fix/loyaltycascade.rb
@ -1,5 +1,11 @@
 # script to fix loyalty cascade, when you order your militia to kill friendly units
 =begin
 fix/loyaltycascade
 ==================
 Aborts loyalty cascades by fixing units whose own civ is the enemy.
 =end
 def fixunit(unit)
    return if unit.race != df.ui.race_id or unit.civ_id != df.ui.civ_id
    links = unit.hist_figure_tg.entity_links
--- a/scripts/fix/population-cap.lua
+++ b/scripts/fix/population-cap.lua
@ -1,11 +1,18 @@
 -- Communicates current population to mountainhomes to avoid cap overshooting.
-- The reason for population cap problems is that the population value it
+--[[=begin
 -- is compared against comes from the last dwarven caravan that successfully
 -- left for mountainhomes. This script instantly updates it.
 -- Note that a migration wave can still overshoot the limit by 1-2 dwarves because
 -- of the last migrant bringing his family. Likewise, king arrival ignores cap.
 fix/population-cap
 ==================
 Run this after every migrant wave to ensure your population cap is not exceeded.
 The reason for population cap problems is that the population value it
 is compared against comes from the last dwarven caravan that successfully
 left for mountainhomes. This script instantly updates it.
 Note that a migration wave can still overshoot the limit by 1-2 dwarves because
 of the last migrant bringing his family. Likewise, king arrival ignores cap.
 =end]]
 local args = {...}
 local ui = df.global.ui
--- a/scripts/fix/stable-temp.lua
+++ b/scripts/fix/stable-temp.lua
@ -1,5 +1,13 @@
 -- Reset item temperature to the value of their tile.
 --[[=begin
 fix/stable-temp
 ===============
 Instantly sets the temperature of all free-lying items to be in equilibrium with
 the environment and stops temperature updates. In order to maintain this efficient
 state however, use `tweak` ``stable-temp`` and `tweak` ``fast-heat``.
 =end]]
 local args = {...}
 local apply = (args[1] == 'apply')
--- a/scripts/fix/stuckdoors.rb
+++ b/scripts/fix/stuckdoors.rb
@ -2,7 +2,14 @@
 # this may happen after people mess with the game by (incorrectly) teleporting units or items
 # a door may stick open if the map occupancy flags are wrong
 =begin
 fix/stuckdoors
 ==============
 Fix doors that are stuck open due to incorrect map occupancy flags, eg due to
 incorrect use of `teleport`.
 =end
 count = 0
 df.world.buildings.all.each { |bld|
    # for all doors
--- a/scripts/gui/advfort.lua
+++ b/scripts/gui/advfort.lua
@ -1,5 +1,26 @@
 -- allows to do jobs in adv. mode.
 --[[=begin
 gui/advfort
 ===========
 This script allows to perform jobs in adventure mode. For more complete help
 press :kbd:`?` while script is running. It's most comfortable to use this as a
 keybinding. (e.g. ``keybinding set Ctrl-T gui/advfort``). Possible arguments:
 :-a, --nodfassign:  uses different method to assign items.
 :-i, --inventory:   checks inventory for possible items to use in the job.
 :-c, --cheat:       relaxes item requirements for buildings (e.g. walls from bones). Implies -a
 :job:               selects that job (e.g. Dig or FellTree)
 An example of player digging in adventure mode:
 .. image:: /docs/images/advfort.png
 **WANRING:**  changes only persist in non procedural sites, namely: player forts, caves, and camps.
 =end]]
 --[==[
    version: 0.044
    changelog:
--- a/scripts/gui/advfort_items.lua
+++ b/scripts/gui/advfort_items.lua
@ -1,3 +1,11 @@
 --[[=begin
 gui/advfort_items
 =================
 Does something with items in adventure mode jobs.
 =end]]
 local _ENV = mkmodule('hack.scripts.gui.advfort_items')
 local gui=require('gui')
--- a/scripts/gui/assign-rack.lua
+++ b/scripts/gui/assign-rack.lua
@ -1,7 +1,15 @@
 -- Assign weapon racks to squads. Requires the weaponrack-unassign patch.
-- See bug 1445 for more info about the patches.
+--[[=begin
 gui/assign-rack
 ===============
 `This script requires a binpatch <binpatches/needs-patch>`, which has not
 been available since DF 0.34.11
 See :bug:`1445` for more info about the patches.
 =end]]
 local utils = require 'utils'
 local gui = require 'gui'
 local guidm = require 'gui.dwarfmode'
--- a/scripts/gui/autobutcher.lua
+++ b/scripts/gui/autobutcher.lua
@ -1,5 +1,11 @@
 -- A GUI front-end for the autobutcher plugin.
 --[[=begin
 gui/autobutcher
 ===============
 An in-game interface for `autobutcher`.
 =end]]
 local gui = require 'gui'
 local utils = require 'utils'
 local widgets = require 'gui.widgets'
--- a/scripts/gui/choose-weapons.lua
+++ b/scripts/gui/choose-weapons.lua
@ -1,5 +1,20 @@
 -- Rewrite individual choice weapons into specific types.
 --[[=begin
 gui/choose-weapons
 ==================
 Bind to a key (the example config uses :kbd:`Ctrl`:kbd:`W`), and activate in the Equip->View/Customize
 page of the military screen.
 Depending on the cursor location, it rewrites all 'individual choice weapon' entries
 in the selected squad or position to use a specific weapon type matching the assigned
 unit's top skill. If the cursor is in the rightmost list over a weapon entry, it rewrites
 only that entry, and does it even if it is not 'individual choice'.
 Rationale: individual choice seems to be unreliable when there is a weapon shortage,
 and may lead to inappropriate weapons being selected.
 =end]]
 local utils = require 'utils'
 local dlg = require 'gui.dialogs'
--- a/scripts/gui/clone-uniform.lua
+++ b/scripts/gui/clone-uniform.lua
@ -1,5 +1,15 @@
 -- Clone the current uniform template in the military screen.
 --[[=begin
 gui/clone-uniform
 =================
 Bind to a key (the example config uses :kbd:`Ctrl`:kbd:`C`), and activate in the Uniforms
 page of the military screen with the cursor in the leftmost list.
 When invoked, the script duplicates the currently selected uniform template,
 and selects the newly created copy.
 =end]]
 local utils = require 'utils'
 local gui = require 'gui'
--- a/scripts/gui/companion-order.lua
+++ b/scripts/gui/companion-order.lua
@ -1,4 +1,24 @@
 --[[=begin
 gui/companion-order
 ===================
 A script to issue orders for companions. Select companions with lower case chars, issue orders with upper
 case. Must be in look or talk mode to issue command on tile.
 .. image:: /docs/images/companion-order.png
 * move - orders selected companions to move to location. If companions are following they will move no more than 3 tiles from you.
 * equip - try to equip items on the ground.
 * pick-up - try to take items into hand (also wield)
 * unequip - remove and drop equipment
 * unwield - drop held items
 * wait - temporarily remove from party
 * follow - rejoin the party after "wait"
 * leave - remove from party (can be rejoined by talking)
 =end]]
 local gui = require 'gui'
 local dlg = require 'gui.dialogs'
 local args={...}
--- a/scripts/gui/create-item.lua
+++ b/scripts/gui/create-item.lua
@ -4,7 +4,13 @@
 -- edited by expwnent
 --@module = true
 --[[=begin
 gui/create-item
 ===============
 A graphical interface for creating items.
 =end]]
 local function getGenderString(gender)
 local genderStr
 if gender==0 then
--- a/scripts/gui/dfstatus.lua
+++ b/scripts/gui/dfstatus.lua
@ -1,6 +1,14 @@
 -- a quick access status screen
 -- originally written by enjia2000@gmail.com (stolencatkarma)
 --[[=begin
 gui/dfstatus
 ============
 Show a quick overview of critical stock quantities, including food, drinks, wood, and various bars.
 Sections can be enabled/disabled/configured by editing ``dfhack-config/dfstatus.lua``.
 =end]]
 local gui = require 'gui'
 function warn(msg)
--- a/scripts/gui/gm-editor.lua
+++ b/scripts/gui/gm-editor.lua
@ -1,4 +1,26 @@
 -- Interface powered item editor.
 --[[=begin
 gui/gm-editor
 =============
 There are three ways to open this editor:
 * using gui/gm-editor command/keybinding - opens editor on what is selected
  or viewed (e.g. unit/item description screen)
 * using gui/gm-editor <lua command> - executes lua command and opens editor on
  its results (e.g. ``gui/gm-editor "df.global.world.items.all"`` shows all items)
 * using gui/gm-editor dialog - shows an in game dialog to input lua command. Works
  the same as version above.
 .. image:: /docs/images/gm-editor.png
 This editor allows to change and modify almost anything in df. Press :kbd:`?` for
 in-game help.
 =end]]
 local gui = require 'gui'
 local dialog = require 'gui.dialogs'
 local widgets =require 'gui.widgets'
--- a/scripts/gui/gm-unit.lua
+++ b/scripts/gui/gm-unit.lua
@ -1,4 +1,12 @@
 -- Interface powered (somewhat user friendly) unit editor.
 --[[=begin
 gui/gm-unit
 ===========
 An editor for various unit attributes.
 =end]]
 local gui = require 'gui'
 local dialog = require 'gui.dialogs'
 local widgets =require 'gui.widgets'
--- a/scripts/gui/guide-path.lua
+++ b/scripts/gui/guide-path.lua
@ -1,5 +1,17 @@
 -- Show and manipulate the path used by Guide Cart orders.
 --[[=begin
 gui/guide-path
 ==============
 Bind to a key (the example config uses :kbd:`Alt`:kbd:`P`), and activate in the Hauling menu with
 the cursor over a Guide order.
 .. image:: /docs/images/guide-path.png
 The script displays the cached path that will be used by the order; the game
 computes it when the order is executed for the first time.
 =end]]
 local utils = require 'utils'
 local gui = require 'gui'
 local guidm = require 'gui.dwarfmode'
--- a/scripts/gui/hack-wish.lua
+++ b/scripts/gui/hack-wish.lua
@ -1 +1,8 @@
 --@ alias = 'gui/create-item'
 --[[=begin
 gui/hack-wish
 =============
 An alias for `gui/create-item`.  Deprecated.
 =end]]
--- a/scripts/gui/hello-world.lua
+++ b/scripts/gui/hello-world.lua
@ -1,5 +1,11 @@
 -- Test lua viewscreens.
 --[[=begin
 gui/hello-world
 ===============
 A basic example for testing, or to start your own script from.
 =end]]
 local gui = require 'gui'
 local text = 'Woohoo, lua viewscreen :)'
--- a/scripts/gui/liquids.lua
+++ b/scripts/gui/liquids.lua
@ -1,5 +1,36 @@
 -- Interface front-end for liquids plugin.
 --[[=begin
 gui/liquids
 ===========
 To use, bind to a key (the example config uses Alt-L) and activate in the :kbd:`k` mode.
 .. image:: /docs/images/liquids.png
 This script is a gui front-end to `liquids` and works similarly,
 allowing you to add or remove water & magma, and create obsidian walls & floors.
 .. warning::
    There is **no undo support**.  Bugs in this plugin have been
    known to create pathfinding problems and heat traps.
 The :kbd:`b` key changes how the affected area is selected. The default *Rectangle*
 mode works by selecting two corners like any ordinary designation. The :kbd:`p`
 key chooses between adding water, magma, obsidian walls & floors, or just
 tweaking flags.
 When painting liquids, it is possible to select the desired level with :kbd:`+`:kbd:`-`,
 and choose between setting it exactly, only increasing or only decreasing
 with :kbd:`s`.
 In addition, :kbd:`f` allows disabling or enabling the flowing water computations
 for an area, and :kbd:`r` operates on the "permanent flow" property that makes
 rivers power water wheels even when full and technically not flowing.
 After setting up the desired operations using the described keys, use :kbd:`Enter` to apply them.
 =end]]
 local utils = require 'utils'
 local gui = require 'gui'
 local guidm = require 'gui.dwarfmode'
--- a/scripts/gui/mechanisms.lua
+++ b/scripts/gui/mechanisms.lua
@ -1,5 +1,22 @@
 -- Shows mechanisms linked to the current building.
 --[[=begin
 gui/mechanisms
 ==============
 To use, bind to a key (the example config uses :kbd:`Ctrl`:kbd:`M`)
 and activate in :kbd:`q` mode.
 .. image:: /docs/images/mechanisms.png
 Lists mechanisms connected to the building, and their links. Navigating
 the list centers the view on the relevant linked buildings.
 To exit, press :kbd:`Esc` or :kbd:`Enter`; :kbd:`Esc` recenters on
 the original building, while :kbd:`Enter` leaves focus on the current
 one. :kbd:`Shift`:kbd:`Enter` has an effect equivalent to pressing
 :kbd:`Enter`, and then re-entering the mechanisms UI.
 =end]]
 local utils = require 'utils'
 local gui = require 'gui'
 local guidm = require 'gui.dwarfmode'
--- a/scripts/gui/mod-manager.lua
+++ b/scripts/gui/mod-manager.lua
@ -1,7 +1,20 @@
 -- a graphical mod manager for df
 local gui=require 'gui'
 local widgets=require 'gui.widgets'
 --[[=begin
 gui/mod-manager
 ===============
 A simple way to install and remove small mods.
 It looks for specially formatted mods in df subfolder 'mods'. Mods are not
 included, but some examples are `available here`_.
 .. _`available here`: https://github.com/warmist/df-mini-mods
 .. image:: /docs/images/mod-manager.png
 =end]]
 local entity_file=dfhack.getDFPath().."/raw/objects/entity_default.txt"
 local init_file=dfhack.getDFPath().."/raw/init.lua"
 local mod_dir=dfhack.getDFPath().."/hack/mods"
--- a/scripts/gui/no-dfhack-init.lua
+++ b/scripts/gui/no-dfhack-init.lua
@ -1,5 +1,11 @@
 -- Shows the warning about missing configuration file.
 --[[=begin
 gui/no-dfhack-init
 ==================
 Shows a warning at startup if no valid :file:`dfhack.init` file is found.
 =end]]
 local gui = require 'gui'
 local dlg = require 'gui.dialogs'
--- a/scripts/gui/power-meter.lua
+++ b/scripts/gui/power-meter.lua
@ -1,5 +1,11 @@
 -- Interface front-end for power-meter plugin.
 --[[=begin
 gui/power-meter
 ===============
 An in-game interface for `power-meter`.
 =end]]
 local utils = require 'utils'
 local gui = require 'gui'
 local guidm = require 'gui.dwarfmode'
--- a/scripts/gui/rename.lua
+++ b/scripts/gui/rename.lua
@ -1,5 +1,35 @@
 -- Rename various objects via gui.
 --[[=begin
 gui/rename
 ==========
 Backed by `rename`, this script allows entering the desired name
 via a simple dialog in the game ui.
 * ``gui/rename [building]`` in :kbd:`q` mode changes the name of a building.
  .. image:: /docs/images/rename-bld.png
  The selected building must be one of stockpile, workshop, furnace, trap, or siege engine.
  It is also possible to rename zones from the :kbd:`i` menu.
 * ``gui/rename [unit]`` with a unit selected changes the nickname.
  Unlike the built-in interface, this works even on enemies and animals.
 * ``gui/rename unit-profession`` changes the selected unit's custom profession name.
  .. image:: /docs/images/rename-prof.png
  Likewise, this can be applied to any unit, and when used on animals it overrides
  their species string.
 The ``building`` or ``unit`` options are automatically assumed when in relevant UI state.
 The example config binds building/unit rename to :kbd:`Ctrl`:kbd:`Shift`:kbd:`N`, and
 unit profession change to :kbd:`Ctrl`:kbd:`Shift`:kbd:`T`.
 =end]]
 local gui = require 'gui'
 local dlg = require 'gui.dialogs'
 local plugin = require 'plugins.rename'
--- a/scripts/gui/room-list.lua
+++ b/scripts/gui/room-list.lua
@ -1,5 +1,17 @@
 -- Browses rooms owned by a unit.
 --[[=begin
 gui/room-list
 =============
 To use, bind to a key (the example config uses :kbd:`Alt`:kbd:`R`) and activate in :kbd:`q` mode,
 either immediately or after opening the assign owner page.
 .. image:: /docs/images/room-list.png
 The script lists other rooms owned by the same owner, or by the unit selected in the assign
 list, and allows unassigning them.
 =end]]
 local utils = require 'utils'
 local gui = require 'gui'
 local guidm = require 'gui.dwarfmode'
--- a/scripts/gui/siege-engine.lua
+++ b/scripts/gui/siege-engine.lua
@ -1,5 +1,11 @@
 -- Front-end for the siege engine plugin.
 --[[=begin
 gui/siege-engine
 ================
 An in-game interface for `siege-engine`.
 =end]]
 local utils = require 'utils'
 local gui = require 'gui'
 local guidm = require 'gui.dwarfmode'
--- a/scripts/gui/stockpiles.lua
+++ b/scripts/gui/stockpiles.lua
@ -1,5 +1,22 @@
 -- lave/load stockpile settings with a GUI
 --[[=begin
 gui/stockpiles
 ==============
 An in-game interface for `stocksettings`, to
 load and save stockpile settings from the :kbd:`q` menu.
 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.
 =end]]
 local stock = require 'plugins.stockpiles'
 function check_enabled()
--- a/scripts/gui/unit-info-viewer.lua
+++ b/scripts/gui/unit-info-viewer.lua
@ -3,7 +3,14 @@
 -- version 1.04
 -- original author: Kurik Amudnil
 -- edited by expwnent
 --[[=begin
 gui/unit-info-viewer
 ====================
 Displays age, birth, maxage, shearing, milking, grazing, egg laying, body size,
 and death info about a unit. Recommended keybinding :kbd:`Alt`:kbd:`I`.
 =end]]
 local gui = require 'gui'
 local widgets =require 'gui.widgets'
 local utils = require 'utils'
--- a/scripts/gui/workflow.lua
+++ b/scripts/gui/workflow.lua
@ -1,5 +1,69 @@
 -- A GUI front-end for the workflow plugin.
 --[[=begin
 gui/workflow
 ============
 Bind to a key (the example config uses Alt-W), and activate with a job selected
 in a workshop in :kbd:`q` mode.
 .. image:: /docs/images/workflow.png
 This script provides a simple interface to constraints managed by `workflow`.
 When active, it displays a list of all constraints applicable to the
 current job, and their current status.
 A constraint specifies a certain range to be compared against either individual
 *item* or whole *stack* count, an item type and optionally a material. When the
 current count is below the lower bound of the range, the job is resumed; if it
 is above or equal to the top bound, it will be suspended. Within the range, the
 specific constraint has no effect on the job; others may still affect it.
 Pressing :kbd:`i` switches the current constraint between counting stacks or items.
 Pressing :kbd:`r` lets you input the range directly;
 :kbd:`e`, :kbd:`r`, :kbd:`d`, :kbd:`f` adjust the
 bounds by 5, 10, or 20 depending on the direction and the :kbd:`i` setting (counting
 items and expanding the range each gives a 2x bonus).
 Pressing :kbd:`a` produces a list of possible outputs of this job as guessed by
 workflow, and lets you create a new constraint by choosing one as template. If you
 don't see the choice you want in the list, it likely means you have to adjust
 the job material first using `job` ``item-material`` or `gui/workshop-job`,
 as described in the `workflow` documentation. In this manner, this feature
 can be used for troubleshooting jobs that don't match the right constraints.
 .. image:: /docs/images/workflow-new1.png
 If you select one of the outputs with :kbd:`Enter`, the matching constraint is simply
 added to the list. If you use :kbd:`Shift`:kbd:`Enter`, the interface proceeds to the
 next dialog, which allows you to edit the suggested constraint parameters to
 suit your need, and set the item count range.
 .. image:: /docs/images/workflow-new2.png
 Pressing :kbd:`s` (or, with the example config, Alt-W in the :kbd:`z` stocks screen)
 opens the overall status screen, which was copied from the C++ implementation
 by falconne for better integration with the rest of the lua script:
 .. image:: /docs/images/workflow-status.png
 This screen shows all currently existing workflow constraints, and allows
 monitoring and/or changing them from one screen. The constraint list can
 be filtered by typing text in the field below.
 The color of the stock level number indicates how "healthy" the stock level
 is, based on current count and trend. Bright green is very good, green is good,
 red is bad, bright red is very bad.
 The limit number is also color-coded. Red means that there are currently no
 workshops producing that item (i.e. no jobs). If it's yellow, that means the
 production has been delayed, possibly due to lack of input materials.
 The chart on the right is a plot of the last 14 days (28 half day plots) worth
 of stock history for the selected item, with the rightmost point representing
 the current stock value. The bright green dashed line is the target
 limit (maximum) and the dark green line is that minus the gap (minimum).
 =end]]
 local utils = require 'utils'
 local gui = require 'gui'
 local guidm = require 'gui.dwarfmode'
--- a/scripts/gui/workshop-job.lua
+++ b/scripts/gui/workshop-job.lua
@ -1,5 +1,53 @@
 -- Show and modify properties of jobs in a workshop.
 --[[=begin
 gui/workshop-job
 ================
 Bind to a key (the example config uses :kbd:`Alt`:kbd:`a`), and activate with a job selected in
 a workshop in the :kbd:`q` mode.
 .. image:: /docs/images/workshop-job.png
 The script shows a list of the input reagents of the selected job, and allows changing
 them like the `job` ``item-type`` and `job` ``item-material`` commands.
 Specifically, pressing the :kbd:`i` key pops up a dialog that lets you select an item
 type from a list.
 .. image:: /docs/images/workshop-job-item.png
 Pressing :kbd:`m`, unless the item type does not allow a material,
 lets you choose a material.
 .. image:: /docs/images/workshop-job-material.png
 Since there are a lot more materials than item types, this dialog is more complex
 and uses a hierarchy of sub-menus. List choices that open a sub-menu are marked
 with an arrow on the left.
 .. warning::
  Due to the way input reagent matching works in DF, you must select an item type
  if you select a material, or the material will be matched incorrectly in some cases.
  If you press :kbd:`m` without choosing an item type, the script will auto-choose
  if there is only one valid choice, or pop up an error message box instead of the
  material selection dialog.
 Note that both materials and item types presented in the dialogs are filtered
 by the job input flags, and even the selected item type for material selection,
 or material for item type selection. Many jobs would let you select only one
 input item type.
 For example, if you choose a *plant* input item type for your prepare meal job,
 it will only let you select cookable materials.
 If you choose a *barrel* item instead (meaning things stored in barrels, like
 drink or milk), it will let you select any material, since in this case the
 material is matched against the barrel itself. Then, if you select, say, iron,
 and then try to change the input item type, now it won't let you select *plant*;
 you have to unset the material first.
 =end]]
 local utils = require 'utils'
 local gui = require 'gui'
 local guidm = require 'gui.dwarfmode'