diff --git a/docs/Scripts.rst b/docs/Scripts.rst
index e6c3495ea..6a6deff87 100644
--- 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
 ===========
diff --git a/docs/conf.py b/docs/conf.py
index 6d1942335..bb65f361e 100644
--- 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 = []
diff --git a/scripts/fix/blood-del.lua b/scripts/fix/blood-del.lua
index 907135eb4..88d7d2756 100644
--- 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
diff --git a/scripts/fix/build-location.lua b/scripts/fix/build-location.lua
index 0eea2c780..9df518ec3 100644
--- 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
diff --git a/scripts/fix/dead-units.lua b/scripts/fix/dead-units.lua
index 2d5558179..7687a75cc 100644
--- 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
diff --git a/scripts/fix/fat-dwarves.lua b/scripts/fix/fat-dwarves.lua
index 5394f6770..5c450513e 100644
--- 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
 
diff --git a/scripts/fix/feeding-timers.lua b/scripts/fix/feeding-timers.lua
index 84c6d45de..84fab7086 100644
--- 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")
diff --git a/scripts/fix/item-occupancy.lua b/scripts/fix/item-occupancy.lua
index 09c6b3030..bcf1b8903 100644
--- 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)
diff --git a/scripts/fix/loyaltycascade.rb b/scripts/fix/loyaltycascade.rb
index b1caf9b10..2cf52dd93 100644
--- 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
diff --git a/scripts/fix/population-cap.lua b/scripts/fix/population-cap.lua
index c2e3293fb..483941982 100644
--- 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
--- 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.
+--[[=begin
 
+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
diff --git a/scripts/fix/stable-temp.lua b/scripts/fix/stable-temp.lua
index 63739f8ea..a67bc7658 100644
--- 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')
diff --git a/scripts/fix/stuckdoors.rb b/scripts/fix/stuckdoors.rb
index 249ed5810..f99d0f263 100644
--- 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
diff --git a/scripts/gui/advfort.lua b/scripts/gui/advfort.lua
index f02fd6a69..6a15750e8 100644
--- 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:
diff --git a/scripts/gui/advfort_items.lua b/scripts/gui/advfort_items.lua
index fb4441397..3727bf9a4 100644
--- 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')
diff --git a/scripts/gui/assign-rack.lua b/scripts/gui/assign-rack.lua
index 92535d793..3b18aa13e 100644
--- 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'
diff --git a/scripts/gui/autobutcher.lua b/scripts/gui/autobutcher.lua
index 013406f33..59f3733c1 100644
--- 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'
diff --git a/scripts/gui/choose-weapons.lua b/scripts/gui/choose-weapons.lua
index 85ad62b6e..f545e1d30 100644
--- 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'
 
diff --git a/scripts/gui/clone-uniform.lua b/scripts/gui/clone-uniform.lua
index 2257c655f..9893c3869 100644
--- 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'
 
diff --git a/scripts/gui/companion-order.lua b/scripts/gui/companion-order.lua
index bef1e0968..9d901a4c9 100644
--- 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={...}
diff --git a/scripts/gui/create-item.lua b/scripts/gui/create-item.lua
index 2339c28c2..b32b91a9b 100644
--- 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
diff --git a/scripts/gui/dfstatus.lua b/scripts/gui/dfstatus.lua
index 32758cfbf..9789affbc 100644
--- 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)
diff --git a/scripts/gui/gm-editor.lua b/scripts/gui/gm-editor.lua
index 0743e1907..da0cf73c6 100644
--- 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'
diff --git a/scripts/gui/gm-unit.lua b/scripts/gui/gm-unit.lua
index 485552729..e25ebf944 100644
--- 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'
diff --git a/scripts/gui/guide-path.lua b/scripts/gui/guide-path.lua
index a807e032d..aa77c9dea 100644
--- 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'
diff --git a/scripts/gui/hack-wish.lua b/scripts/gui/hack-wish.lua
index 023ef9321..de423abc2 100644
--- 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]]
\ No newline at end of file
diff --git a/scripts/gui/hello-world.lua b/scripts/gui/hello-world.lua
index 122f2cd38..324aa11ad 100644
--- 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 :)'
diff --git a/scripts/gui/liquids.lua b/scripts/gui/liquids.lua
index 322ae6952..27c454f9e 100644
--- 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'
diff --git a/scripts/gui/mechanisms.lua b/scripts/gui/mechanisms.lua
index 607625524..d65782469 100644
--- 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'
diff --git a/scripts/gui/mod-manager.lua b/scripts/gui/mod-manager.lua
index 2f2aa92ba..3ff46525e 100644
--- 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"
diff --git a/scripts/gui/no-dfhack-init.lua b/scripts/gui/no-dfhack-init.lua
index f6171d5c7..c4352211d 100644
--- 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'
 
diff --git a/scripts/gui/power-meter.lua b/scripts/gui/power-meter.lua
index ac30c9273..51908bd0f 100644
--- 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'
diff --git a/scripts/gui/rename.lua b/scripts/gui/rename.lua
index 70a09b2fa..3433f4881 100644
--- 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'
diff --git a/scripts/gui/room-list.lua b/scripts/gui/room-list.lua
index 1f3e663da..ac6890317 100644
--- 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'
diff --git a/scripts/gui/siege-engine.lua b/scripts/gui/siege-engine.lua
index 1e5200875..a88040470 100644
--- 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'
diff --git a/scripts/gui/stockpiles.lua b/scripts/gui/stockpiles.lua
index 638ae2894..4e2f28281 100644
--- 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()
diff --git a/scripts/gui/unit-info-viewer.lua b/scripts/gui/unit-info-viewer.lua
index 8e42a86c8..1d7cb763d 100644
--- 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'
diff --git a/scripts/gui/workflow.lua b/scripts/gui/workflow.lua
index 77a87c9ce..67b7477fc 100644
--- 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'
diff --git a/scripts/gui/workshop-job.lua b/scripts/gui/workshop-job.lua
index c4e203614..f3af15d10 100644
--- 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'