Move modtools docs

docs/Scripts.rst

@@ -69,121 +69,6 @@ The following pages document all the standard DFHack scripts.
    /scripts/3rdparty/*/*
 
 
-.. _modtools/add-syndrome:
-
-modtools/add-syndrome
-=====================
-This allows adding and removing syndromes from units.
-
-modtools/anonymous-script
-=========================
-This allows running a short simple Lua script passed as an argument instead of
-running a script from a file. This is useful when you want to do something too
-complicated to make with the existing modtools, but too simple to be worth its
-own script file.
-
-modtools/create-item
-====================
-This is mostly the same as the other create item tools, but it uses standard
-arguments. The other versions will be phased out in a later version.
-
-modtools/create-unit
-====================
-Creates a unit.
-
-.. _modtools/equip-item:
-
-modtools/equip-item
-===================
-Force a unit to equip an item; useful in conjunction with the ``create``
-scripts above.
-
-See also `forceequip`.
-
-modtools/force
-==============
-This tool triggers events like megabeasts, caravans, invaders, and migrants.
-
-modtools/interaction-trigger
-============================
-This triggers events when a unit uses an interaction on another. It works by
-scanning the announcements for the correct attack verb, so the attack verb
-must be specified in the interaction. It includes an option to suppress this
-announcement after it finds it.
-
-modtools/invader-item-destroyer
-===============================
-This tool configurably destroys invader items to prevent clutter or to prevent
-the player from getting tools exclusive to certain races.
-
-.. _modtools/item-trigger:
-
-modtools/item-trigger
-=====================
-This powerful tool triggers DFHack commands when a unit equips, unequips, or
-attacks another unit with specified item types, specified item materials, or
-specified item contaminants.
-
-modtools/moddable-gods
-======================
-This is a standardized version of Putnam's moddableGods script. It allows you
-to create gods on the command-line.
-
-modtools/outside-only
-=====================
-This allows you to specify certain custom buildings as outside only, or inside
-only. If the player attempts to build a building in an inappropriate location,
-the building will be destroyed.
-
-modtools/projectile-trigger
-===========================
-This triggers dfhack commands when projectiles hit their targets.
-
-modtools/random-trigger
-=======================
-This triggers random dfhack commands with specified probabilities.
-
-.. _modtools/reaction-product-trigger:
-
-modtools/reaction-product-trigger
-=================================
-This triggers dfhack commands when reaction products are produced, once per
-product.
-
-.. _modtools/reaction-trigger:
-
-modtools/reaction-trigger
-=========================
-Triggers dfhack commands when custom reactions complete, regardless of whether
-it produced anything, once per completion.
-
-.. _modtools/reaction-trigger-transition:
-
-modtools/reaction-trigger-transition
-====================================
-Scans raw files and creates a file to help modders transition from
-autoSyndrome to reaction-trigger.
-
-.. _modtools/skill-change:
-
-modtools/skill-change
-=====================
-Sets or modifies a skill of a unit.
-
-modtools/spawn-flow
-===================
-Creates flows at the specified location.
-
-modtools/syndrome-trigger
-=========================
-Triggers dfhack commands when syndromes are applied to units.
-
-modtools/transform-unit
-=======================
-Transforms a unit into another unit type, possibly permanently.
-
-
-
 ban-cooking
 ===========
 A more convenient way to ban cooking various categories of foods than the

scripts/modtools/add-syndrome.lua

@@ -1,7 +1,12 @@
 --modtools/add-syndrome.lua
 --author expwnent
---add syndromes to a target, or remove them
+--[[=begin
 
+modtools/add-syndrome
+=====================
+This allows adding and removing syndromes from units.
+
+=end]]
 local syndromeUtil = require 'syndrome-util'
 local utils = require 'utils'
 

scripts/modtools/anonymous-script.lua

@@ -1,9 +1,19 @@
 --scripts/modtools/anonymous-script.lua
 --author expwnent
 --a tool for invoking simple lua scripts without putting them in a file first
---anonymous-script "print(args[1])" arg1 arg2
+--[[=begin
---# prints "arg1"
 
+modtools/anonymous-script
+=========================
+This allows running a short simple Lua script passed as an argument instead of
+running a script from a file. This is useful when you want to do something too
+complicated to make with the existing modtools, but too simple to be worth its
+own script file.  Example::
+
+    anonymous-script "print(args[1])" arg1 arg2
+    # prints "arg1"
+
+=end]]
 local args = {...}
 
 --automatically collect arguments to make the anonymous script more succinct

scripts/modtools/create-item.lua

@@ -1,7 +1,14 @@
 --scripts/modtools/create-item.lua
 --author expwnent
 --creates an item of a given type and material
+--[[=begin
 
+modtools/create-item
+====================
+This is mostly the same as the other create item tools, but it uses standard
+arguments. The other versions will be phased out in a later version.
+
+=end]]
 local utils = require 'utils'
 
 validArgs = --[[validArgs or--]] utils.invert({

scripts/modtools/create-unit.lua

@@ -12,6 +12,13 @@
       set invasion_id, etc
     announcement for fake natural birth if appropriate
 ]]
+--[[=begin
+
+modtools/create-unit
+====================
+Creates a unit.  Use ``modtools/create-unit -help`` for more info.
+
+=end]]
 
 --[[
 if dfhack.gui.getCurViewscreen()._type ~= df.viewscreen_dwarfmodest or df.global.ui.main.mode ~= df.ui_sidebar_mode.LookAround then

scripts/modtools/equip-item.lua

@@ -1,6 +1,13 @@
 -- modtools/equip-item.lua
 -- equip an item on a unit with a particular body part
+--[[=begin
 
+modtools/equip-item
+===================
+Force a unit to equip an item with a particular body part; useful in
+conjunction with the ``create`` scripts above.  See also `forceequip`.
+
+=end]]
 local utils = require 'utils'
 
 function equipItem(unit, item, bodyPart, mode)

scripts/modtools/force.lua

@@ -2,7 +2,13 @@
 -- author Putnam
 -- edited by expwnent
 -- Forces an event.
+--[[=begin
 
+modtools/force
+==============
+This tool triggers events like megabeasts, caravans, invaders, and migrants.
+
+=end]]
 local utils = require 'utils'
 
 local function findCiv(arg)

scripts/modtools/interaction-trigger.lua

@@ -1,7 +1,16 @@
 --scripts/modtools/interaction-trigger.lua
 --author expwnent
 --triggers scripts when a unit does a unit interaction on another
+--[[=begin
 
+modtools/interaction-trigger
+============================
+This triggers events when a unit uses an interaction on another. It works by
+scanning the announcements for the correct attack verb, so the attack verb
+must be specified in the interaction. It includes an option to suppress this
+announcement after it finds it.
+
+=end]]
 local eventful = require 'plugins.eventful'
 local utils = require 'utils'
 

scripts/modtools/invader-item-destroyer.lua

@@ -1,7 +1,14 @@
 --scripts/modtools/invader-item-destroyer.lua
 --author expwnent
 --configurably deletes invader items when they die
+--[[=begin
 
+modtools/invader-item-destroyer
+===============================
+This tool configurably destroys invader items to prevent clutter or to prevent
+the player from getting tools exclusive to certain races.
+
+=end]]
 local eventful = require 'plugins.eventful'
 local utils = require 'utils'
 

scripts/modtools/item-trigger.lua

@@ -2,7 +2,15 @@
 --author expwnent
 --based on itemsyndrome by Putnam
 --triggers scripts when a unit attacks another with a weapon type, a weapon of a particular material, or a weapon contaminated with a particular material, or when a unit equips/unequips a particular item type, an item of a particular material, or an item contaminated with a particular material
+--[[=begin
 
+modtools/item-trigger
+=====================
+This powerful tool triggers DFHack commands when a unit equips, unequips, or
+attacks another unit with specified item types, specified item materials, or
+specified item contaminants.
+
+=end]]
 local eventful = require 'plugins.eventful'
 local utils = require 'utils'
 

scripts/modtools/moddable-gods.lua

@@ -1,7 +1,14 @@
 --scripts/modtools/moddable-gods.lua
 --based on moddableGods by Putnam
 --edited by expwnent
+--[[=begin
 
+modtools/moddable-gods
+======================
+This is a standardized version of Putnam's moddableGods script. It allows you
+to create gods on the command-line.
+
+=end]]
 local utils = require 'utils'
 
 validArgs = validArgs or utils.invert({

scripts/modtools/outside-only.lua

@@ -1,7 +1,15 @@
 --scripts/modtools/outsideOnly.lua
 --author expwnent
 --enables outside only and inside only buildings
+--[[=begin
 
+modtools/outside-only
+=====================
+This allows you to specify certain custom buildings as outside only, or inside
+only. If the player attempts to build a building in an inappropriate location,
+the building will be destroyed.
+
+=end]]
 local eventful = require 'plugins.eventful'
 local utils = require 'utils'
 

scripts/modtools/projectile-trigger.lua

@@ -2,7 +2,13 @@
 --author expwnent
 --based on Putnam's projectileExpansion
 --TODO: trigger based on contaminants
+--[[=begin
 
+modtools/projectile-trigger
+===========================
+This triggers dfhack commands when projectiles hit their targets.
+
+=end]]
 local eventful = require 'plugins.eventful'
 local utils = require 'utils'
 

scripts/modtools/random-trigger.lua

@@ -1,7 +1,16 @@
 --scripts/modtools/random-trigger.lua
 --triggers random scripts
---register a few scripts, then tell it to "go" and it will pick a random one based on the probability weights you specified. outcomes are mutually exclusive. To make independent random events, call the script multiple times.
+--[[=begin
 
+modtools/random-trigger
+=======================
+This triggers random dfhack commands with specified probabilities.
+Register a few scripts, then tell it to "go" and it will pick one
+based on the probability weights you specified.  Outcomes are mutually
+exclusive. To make independent random events, call the script multiple
+times.
+
+=end]]
 local utils = require 'utils'
 local eventful = require 'plugins.eventful'
 

scripts/modtools/reaction-product-trigger.lua

@@ -2,7 +2,14 @@
 -- author expwnent
 -- trigger commands just before and after custom reactions produce items
 --@ module = true
+--[[=begin
 
+modtools/reaction-product-trigger
+=================================
+This triggers dfhack commands when reaction products are produced, once per
+product.
+
+=end]]
 local eventful = require 'plugins.eventful'
 local utils = require 'utils'
 

scripts/modtools/reaction-trigger-transition.lua

@@ -1,8 +1,18 @@
 -- scripts/modtools/reaction-trigger-transition.lua
 -- author expwnent
--- prints useful things to the console and a file to help modders transition from autoSyndrome to reaction-trigger
+--[[=begin
--- this script is basically an apology for breaking backward compatibiility
 
+modtools/reaction-trigger-transition
+====================================
+Scans raw files and creates a file to help modders transition from
+autoSyndrome to reaction-trigger.
+
+Prints useful things to the console and a file to help modders
+transition from autoSyndrome to reaction-trigger.  This script
+is basically an apology for breaking backward compatibiility,
+and will be removed eventually.
+
+=end]]
 local function maybeQuote(str)
  if str == '' or string.find(str,' ') then
   return ('"' .. str .. '"')

scripts/modtools/reaction-trigger.lua

@@ -2,7 +2,15 @@
 -- author expwnent
 -- replaces autoSyndrome: trigger commands when custom reactions are completed
 --@ module = true
+--[[=begin
 
+modtools/reaction-trigger
+=========================
+Triggers dfhack commands when custom reactions complete, regardless of whether
+it produced anything, once per completion.  Use the ``-help`` command
+for more information.
+
+=end]]
 local eventful = require 'plugins.eventful'
 local syndromeUtil = require 'syndrome-util'
 local utils = require 'utils'

scripts/modtools/skill-change.lua

@@ -3,7 +3,21 @@
 --based on skillChange.lua by Putnam
 --TODO: update skill level once experience increases/decreases
 --TODO: skill rust?
+--[[=begin
 
+modtools/skill-change
+=====================
+Sets or modifies a skill of a unit.  Args:
+
+:-help:             print the help message
+:-skill skillName:  set the skill that we're talking about
+:-mode (add/set):   are we adding experience/levels or setting them?
+:-granularity (experience/level):
+                    direct experience, or experience levels?
+:-unit id:          id of the target unit
+:-value amount:     how much to set/add
+
+=end]]
 local utils = require 'utils'
 
 validArgs = validArgs or utils.invert({

scripts/modtools/spawn-flow.lua

@@ -1,7 +1,13 @@
 --scripts/modtools/spawn-flow.lua
 --author expwnent
 --spawns flows at locations
+--[[=begin
 
+modtools/spawn-flow
+===================
+Creates flows at the specified location.
+
+=end]]
 local utils = require 'utils'
 
 validArgs = validArgs or utils.invert({

scripts/modtools/syndrome-trigger.lua

@@ -1,7 +1,13 @@
 --scripts/modtools/syndrome-trigger.lua
 --author expwnent
 --triggers scripts when units are infected with syndromes
+--[[=begin
 
+modtools/syndrome-trigger
+=========================
+Triggers dfhack commands when syndromes are applied to units.
+
+=end]]
 local eventful = require 'plugins.eventful'
 local utils = require 'utils'
 

scripts/modtools/transform-unit.lua

@@ -1,9 +1,15 @@
 --scripts/modtools/transform-unit.lua
 --author expwnent
 --based on shapechange by Putnam
---warning: will crash arena mode if you view the unit on the same tick that it transforms
+--[[=begin
---if you wait until later, it will be fine
 
+modtools/transform-unit
+=======================
+Transforms a unit into another unit type, possibly permanently.
+Warning: this will crash arena mode if you view the unit on the
+same tick that it transforms.  If you wait until later, it will be fine.
+
+=end]]
 local utils = require 'utils'
 
 normalRace = normalRace or {}