Merge branch 'develop' of https://github.com/dfhack/dfhack into develop

docs/Contributing.rst

@@ -137,6 +137,11 @@ there are a few important standards for completeness and consistent style.  Trea
 this section as a guide rather than iron law, match the surrounding text, and you'll
 be fine.
 
+Each command should have a short (~54 character) help string, which is shown
+by the `ls` command.  For scripts, this is a comment on the first line
+(the comment marker and whitespace is stripped).  For plugins it's the second
+argument to ``PluginCommand``.  Please make this brief but descriptive!
+
 Everything should be documented!  If it's not clear *where* a particular
 thing should be documented, ask on IRC or in the DFHack thread on Bay12 -
 as well as getting help, you'll be providing valuable feedback that

docs/Plugins.rst

@@ -157,7 +157,7 @@ Usage and related commands:
 
 :reveal:        Reveal the whole map, except for HFS to avoid demons spawning
 :reveal hell:   Also show hell, but requires ``unreveal`` before unpausing
-:reveal demons: Reveals everything and allows unpausing - good luck!
+:reveal demon:  Reveals everything and allows unpausing - good luck!
 :unreveal:      Reverts the effects of ``reveal``
 :revtoggle:     Switches between ``reveal`` and ``unreveal``
 :revflood:      Hide everything, then reveal tiles with a path to the cursor
@@ -275,7 +275,7 @@ One-shot subcommands:
 
 Subcommands that persist until disabled or DF quits:
 
-:adamantine-cloth-wear: Prevents adamantine clothing from wearing out while being worn (bug 6481).
+:adamantine-cloth-wear: Prevents adamantine clothing from wearing out while being worn (:bug:`6481`).
 :advmode-contained:     Works around :bug:`6202`, custom reactions with container inputs
                         in advmode. The issue is that the screen tries to force you to select
                         the contents separately from the container. This forcefully skips child
@@ -1083,7 +1083,7 @@ This plugin adds an option to the :kbd:`q` menu for stckpiles when `enabled <ena
 When autodump is enabled for a stockpile, any items placed in the stockpile will
 automatically be designated to be dumped.
 
-ALternatively, you can use it to quickly move all items designated to be dumped.
+Alternatively, you can use it to quickly move all items designated to be dumped.
 Items are instantly moved to the cursor position, the dump flag is unset,
 and the forbid flag is set, as if it had been dumped normally.
 Be aware that any active dump item tasks still point at the item.
@@ -1187,7 +1187,9 @@ Some widgets support additional options:
     * ``D``: The current day, zero-padded if necessary
     * ``d``: The current day, *not* zero-padded
 
-    The default date format is ``Y-M-D``, per the ISO8601 standard.
+    The default date format is ``Y-M-D``, per the ISO8601_ standard.
+
+    .. _ISO8601: https://en.wikipedia.org/wiki/ISO_8601
 
 * ``cursor`` widget:
 
@@ -1868,9 +1870,8 @@ is an optional description of where that is. You may also leave a description
 of the contents of the file itself following the closing parenthesis on the
 same line.
 
-The syntax of the file itself is similar to `digfort` or
+The syntax of the file itself is similar to `digfort` or :forums:`quickfort <35931>`.
-`quickfort <http://www.bay12forums.com/smf/index.php?topic=35931>`_. At present,
+At present, only buildings constructed of an item with the same name as the building
-only buildings constructed of an item with the same name as the building
 are supported. All other characters are ignored. For example::
 
     `,`,d,`,`
@@ -1881,7 +1882,7 @@ This section of a file would designate for construction a door and some
 furniture inside a bedroom: specifically, clockwise from top left, a cabinet,
 a table, a chair, a bed, and a statue.
 
-All of the building designation uses `Planning Mode <buildingplan>`, so you do not need to
+All of the building designation uses `buildingplan`, so you do not need to
 have the items available to construct all the buildings when you run
 fortplan with the .csv file.
 

plugins/autochop.cpp

@@ -791,7 +791,7 @@ DFhackCExport command_result plugin_enable(color_ostream &out, bool enable)
 DFhackCExport command_result plugin_init ( color_ostream &out, vector <PluginCommand> &commands)
 {
     commands.push_back(PluginCommand(
-        "autochop", "Allows automatic harvesting of trees based on the number of stockpiled logs",
+        "autochop", "Auto-harvest trees when low on stockpiled logs",
         df_autochop, false,
         "Opens the automated chopping control screen. Specify 'debug' to forcibly save settings.\n"
     ));

plugins/automelt.cpp

@@ -299,7 +299,7 @@ DFhackCExport command_result plugin_init ( color_ostream &out, std::vector <Plug
 {
     commands.push_back(
         PluginCommand(
-        "automelt", "Automatically flag metal items in marked stockpiles for melting.",
+        "automelt", "Automatically melt metal items in marked stockpiles.",
         automelt_cmd, false, ""));
 
     return CR_OK;

plugins/cleaners.cpp

@@ -236,7 +236,7 @@ command_result clean (color_ostream &out, vector <string> & parameters)
 DFhackCExport command_result plugin_init ( color_ostream &out, std::vector <PluginCommand> &commands)
 {
     commands.push_back(PluginCommand(
-        "clean","Removes contaminants from map tiles, items and creatures.",
+        "clean","Remove contaminants from tiles, items and creatures.",
         clean, false,
         "  Removes contaminants from map tiles, items and creatures.\n"
         "Options:\n"

plugins/cursecheck.cpp

@@ -58,7 +58,7 @@ command_result cursecheck (color_ostream &out, vector <string> & parameters);
 DFhackCExport command_result plugin_init ( color_ostream &out, std::vector <PluginCommand> &commands)
 {
     commands.push_back(PluginCommand("cursecheck",
-        "Checks for cursed creatures (vampires, necromancers, zombies, ...).",
+        "Check for cursed creatures (undead, necromancers...)",
         cursecheck, false ));
     return CR_OK;
 }

plugins/deramp.cpp

@@ -83,7 +83,7 @@ command_result df_deramp (color_ostream &out, vector <string> & parameters)
 DFhackCExport command_result plugin_init ( color_ostream &out, std::vector <PluginCommand> &commands)
 {
     commands.push_back(PluginCommand(
-        "deramp", "De-ramp. All ramps marked for removal are replaced with floors.",
+        "deramp", "Replace all ramps marked for removal with floors.",
         df_deramp, false,
         "  If there are any ramps designated for removal, they will be instantly\n"
         "  removed. Any ramps that don't have their counterpart will also be removed\n"

plugins/devel/kittens.cpp

@@ -42,7 +42,7 @@ DFHACK_PLUGIN("kittens");
 DFhackCExport command_result plugin_init ( color_ostream &out, std::vector <PluginCommand> &commands)
 {
     commands.push_back(PluginCommand("nyan","NYAN CAT INVASION!",kittens));
-    commands.push_back(PluginCommand("ktimer","Measure time between game updates and console lag (toggle).",ktimer));
+    commands.push_back(PluginCommand("ktimer","Measure time between game updates and console lag.",ktimer));
     commands.push_back(PluginCommand("trackmenu","Track menu ID changes (toggle).",trackmenu));
     commands.push_back(PluginCommand("trackpos","Track mouse and designation coords (toggle).",trackpos));
     commands.push_back(PluginCommand("trackstate","Track world and map state (toggle).",trackstate));

plugins/devel/memview.cpp

@@ -36,7 +36,7 @@ DFHACK_PLUGIN("memview");
 
 DFhackCExport command_result plugin_init (color_ostream &out, std::vector <PluginCommand> &commands)
 {
-    commands.push_back(PluginCommand("memview","Shows memory in real time. Params: adrr length refresh_rate. If addr==0 then stop viewing",memview));
+    commands.push_back(PluginCommand("memview","Shows DF memory in real time.",memview,false,"Shows memory in real time.\nParams: adrr length refresh_rate. If addr==0 then stop viewing."));
     memdata.state=STATE_OFF;
     mymutex=new tthread::mutex;
     return CR_OK;

plugins/devel/rprobe.cpp

@@ -45,7 +45,7 @@ DFHACK_PLUGIN("rprobe");
 DFhackCExport command_result plugin_init ( color_ostream &out, std::vector <PluginCommand> &commands)
 {
     commands.push_back(PluginCommand(
-        "rprobe", "Display assorted region information from embark screen",
+        "rprobe", "Display region information from embark screen",
         rprobe, false,
         "Display assorted region information from embark screen\n"
     ));

plugins/dig.cpp

@@ -55,8 +55,8 @@ DFhackCExport command_result plugin_init ( color_ostream &out, std::vector <Plug
         "  Designates layerstone under the cursor for digging.\n"
         "  Also follows the stone between z-levels with stairs, like 'digl x' would.\n"
         ));
-    commands.push_back(PluginCommand("digexp","Select or designate an exploratory pattern. Use 'digexp ?' for help.",digexp));
+    commands.push_back(PluginCommand("digexp","Select or designate an exploratory pattern.",digexp));
-    commands.push_back(PluginCommand("digcircle","Dig designate a circle (filled or hollow) with given diameter.",digcircle));
+    commands.push_back(PluginCommand("digcircle","Dig designate a circle (filled or hollow)",digcircle));
     //commands.push_back(PluginCommand("digauto","Mark a tile for continuous digging.",autodig));
     commands.push_back(PluginCommand("digtype", "Dig all veins of a given type.", digtype,Gui::cursor_hotkey,
         "For every tile on the map of the same vein type as the selected tile, this command designates it to have the same designation as the selected tile. If the selected tile has no designation, they will be dig designated.\n"

plugins/fastdwarf.cpp

@@ -246,7 +246,7 @@ DFhackCExport command_result plugin_enable ( color_ostream &out, bool enable )
 DFhackCExport command_result plugin_init ( color_ostream &out, std::vector <PluginCommand> &commands)
 {
     commands.push_back(PluginCommand("fastdwarf",
-        "enable/disable fastdwarf and teledwarf (parameters=0/1)",
+        "let dwarves teleport and/or finish jobs instantly",
         fastdwarf, false,
         "fastdwarf: make dwarves faster.\n"
         "Usage:\n"

plugins/filltraffic.cpp

@@ -44,7 +44,7 @@ DFHACK_PLUGIN("filltraffic");
 DFhackCExport command_result plugin_init ( color_ostream &out, std::vector <PluginCommand> &commands)
 {
     commands.push_back(PluginCommand(
-        "filltraffic","Flood-fill with selected traffic designation from cursor",
+        "filltraffic","Flood-fill selected traffic designation from cursor",
         filltraffic, Gui::cursor_hotkey,
         "  Flood-fill selected traffic type from the cursor.\n"
         "Traffic Type Codes:\n"

plugins/follow.cpp

@@ -29,7 +29,7 @@ uint8_t prevMenuWidth;
 DFhackCExport command_result plugin_init ( color_ostream &out, std::vector <PluginCommand> &commands)
 {
     commands.push_back(PluginCommand(
-        "follow", "Follow the selected unit until camera control is released",
+        "follow", "Make the screen follow the selected unit",
         follow, Gui::view_unit_hotkey,
         "  Select a unit and run this plugin to make the camera follow it.\n"
         "  Moving the camera yourself deactivates the plugin.\n"

plugins/forceequip.cpp

@@ -216,7 +216,7 @@ const string forceequip_help =
 DFhackCExport command_result plugin_init ( color_ostream &out, vector <PluginCommand> &commands)
 {
     commands.push_back(PluginCommand(
-        "forceequip", "Moves local items from the ground into a unit's inventory",
+        "forceequip", "Move items from the ground into a unit's inventory",
         df_forceequip, false,
         forceequip_help.c_str()
     ));

plugins/fortplan.cpp

@@ -51,7 +51,7 @@ public:
 std::vector<BuildingInfo> buildings;
 
 DFhackCExport command_result plugin_init ( color_ostream &out, vector <PluginCommand> &commands) {
-    commands.push_back(PluginCommand("fortplan","Lay out buildings in your fortress based on a Quickfort-style CSV input file.",fortplan,false,
+    commands.push_back(PluginCommand("fortplan","Lay out buildings from a Quickfort-style CSV file.",fortplan,false,
         "Lay out buildings in your fortress based on a Quickfort-style CSV input file.\n"
         "Usage: fortplan [filename]\n"));
 

plugins/getplants.cpp

@@ -152,7 +152,7 @@ command_result df_getplants (color_ostream &out, vector <string> & parameters)
 DFhackCExport command_result plugin_init ( color_ostream &out, vector <PluginCommand> &commands)
 {
     commands.push_back(PluginCommand(
-        "getplants", "Cut down all of the specified trees or gather specified shrubs",
+        "getplants", "Cut down trees or gather shrubs by ID",
         df_getplants, false,
         "  Specify the types of trees to cut down and/or shrubs to gather by their\n"
         "  plant IDs, separated by spaces.\n"

plugins/hotkeys.cpp

@@ -354,7 +354,7 @@ DFhackCExport command_result plugin_init ( color_ostream &out, std::vector <Plug
 
     commands.push_back(
         PluginCommand(
-        "hotkeys", "Shows ingame viewscreen with all dfhack keybindings active in current mode.",
+        "hotkeys", "Show all dfhack keybindings in current context.",
         hotkeys_cmd, false, ""));
 
     return CR_OK;

plugins/infiniteSky.cpp

@@ -32,7 +32,7 @@ DFhackCExport command_result plugin_init ( color_ostream &out, std::vector <Plug
 {
     commands.push_back(PluginCommand(
         "infiniteSky",
-        "Creates new sky levels on request, or as you construct up.",
+        "Creates new sky levels on request, or as needed.",
         infiniteSky, false,
         "Usage:\n"
         "  infiniteSky\n"

plugins/lair.cpp

@@ -58,7 +58,7 @@ command_result lair(color_ostream &out, std::vector<std::string> & params)
 
 DFhackCExport command_result plugin_init ( color_ostream &out, std::vector <PluginCommand> &commands)
 {
-    commands.push_back(PluginCommand("lair","Mark the map as a monster lair, preventing item scatter.",lair, false,
+    commands.push_back(PluginCommand("lair","Mark the map as a monster lair (avoids item scatter)",lair, false,
         "Usage: 'lair' to mark entire map as monster lair, 'lair reset' to undo the operation.\n"));
     return CR_OK;
 }

plugins/petcapRemover.cpp

@@ -36,7 +36,7 @@ DFhackCExport command_result plugin_init ( color_ostream &out, std::vector <Plug
 {
     commands.push_back(PluginCommand(
         "petcapRemover",
-        "Removes the pet population cap by causing pregnancies.",
+        "Remove the pet population cap by causing pregnancies.",
         petcapRemover,
         false, //allow non-interactive use
         "petcapRemover\n"

plugins/proto/RemoteFortressReader.proto

@@ -100,6 +100,23 @@ enum BuildingDirection
     WEST = 3;
 }
 
+enum TileDigDesignation
+{
+        /**
+         * no designation
+         */
+        NO_DIG = 0;
+        /**
+         * dig walls, remove stairs and ramps, gather plants, fell trees
+         */
+        DEFAULT_DIG = 1;
+        UP_DOWN_STAIR_DIG = 2;
+        CHANNEL_DIG = 3;
+        RAMP_DIG = 4;
+        DOWN_STAIR_DIG = 5;
+        UP_STAIR_DIG = 6;
+}
+
 message Tiletype
 {
     required int32 id = 1;
@@ -168,6 +185,7 @@ message MapBlock
     repeated int32 tree_x = 21;
     repeated int32 tree_y = 22;
     repeated int32 tree_z = 23;
+    repeated TileDigDesignation tile_dig_designation = 24;
 }
 
 message MatPair {

plugins/remotefortressreader.cpp

@@ -1149,8 +1149,6 @@ void CopyDesignation(df::map_block * DfBlock, RemoteFortressReader::MapBlock * N
     NetBlock->set_map_y(DfBlock->map_pos.y);
     NetBlock->set_map_z(DfBlock->map_pos.z);
 
-    bool hasBuilding = false;
-
     for (int yy = 0; yy < 16; yy++)
         for (int xx = 0; xx < 16; xx++)
         {
@@ -1170,12 +1168,33 @@ void CopyDesignation(df::map_block * DfBlock, RemoteFortressReader::MapBlock * N
             NetBlock->add_subterranean(designation.bits.subterranean);
             NetBlock->add_water_salt(designation.bits.water_salt);
             NetBlock->add_water_stagnant(designation.bits.water_stagnant);
-        }
+            switch (designation.bits.dig)
-
+            {
-    if(hasBuilding)
+            case df::enums::tile_dig_designation::No:
-        for (int i = 0; i < df::global::world->buildings.all.size(); i++)
+                NetBlock->add_tile_dig_designation(TileDigDesignation::NO_DIG);
-        {
+                break;
-
+            case df::enums::tile_dig_designation::Default:
+                NetBlock->add_tile_dig_designation(TileDigDesignation::DEFAULT_DIG);
+                break;
+            case df::enums::tile_dig_designation::UpDownStair:
+                NetBlock->add_tile_dig_designation(TileDigDesignation::UP_DOWN_STAIR_DIG);
+                break;
+            case df::enums::tile_dig_designation::Channel:
+                NetBlock->add_tile_dig_designation(TileDigDesignation::CHANNEL_DIG);
+                break;
+            case df::enums::tile_dig_designation::Ramp:
+                NetBlock->add_tile_dig_designation(TileDigDesignation::RAMP_DIG);
+                break;
+            case df::enums::tile_dig_designation::DownStair:
+                NetBlock->add_tile_dig_designation(TileDigDesignation::DOWN_STAIR_DIG);
+                break;
+            case df::enums::tile_dig_designation::UpStair:
+                NetBlock->add_tile_dig_designation(TileDigDesignation::UP_STAIR_DIG);
+                break;
+            default:
+                NetBlock->add_tile_dig_designation(TileDigDesignation::NO_DIG);
+                break;
+            }
         }
 }
 
@@ -1727,6 +1746,12 @@ static command_result GetWorldMap(color_ostream &stream, const EmptyMessage *in,
         return CR_FAILURE;
     }
     df::world_data * data = df::global::world->world_data;
+    if (!data->region_map)
+    {
+        out->set_world_width(0);
+        out->set_world_height(0);
+        return CR_FAILURE;
+    }
     int width = data->world_width;
     int height = data->world_height;
     out->set_world_width(width);

plugins/resume.cpp

@@ -298,7 +298,7 @@ DFhackCExport command_result plugin_init ( color_ostream &out, std::vector <Plug
 {
     commands.push_back(
         PluginCommand(
-        "resume", "A plugin to help display and resume suspended constructions conveniently",
+        "resume", "Display and easily resume suspended constructions",
         resume_cmd, false,
         "resume show\n"
         "  Show overlay when paused:\n"

plugins/reveal.cpp

@@ -77,7 +77,7 @@ command_result nopause(color_ostream &out, vector<string> & params);
 
 DFhackCExport command_result plugin_init ( color_ostream &out, vector <PluginCommand> &commands)
 {
-    commands.push_back(PluginCommand("reveal","Reveal the map. 'reveal hell' will also reveal hell. 'reveal demon' won't pause.",reveal,false,
+    commands.push_back(PluginCommand("reveal","Reveal the map.",reveal,false,
         "Reveals the map, by default ignoring hell.\n"
         "Options:\n"
         "hell     - also reveal hell, while forcing the game to pause.\n"
@@ -86,12 +86,12 @@ DFhackCExport command_result plugin_init ( color_ostream &out, vector <PluginCom
         "Reverts the previous reveal operation, hiding the map again.\n"));
     commands.push_back(PluginCommand("revtoggle","Reveal/unreveal depending on state.",revtoggle,false,
         "Toggles between reveal and unreveal.\n"));
-    commands.push_back(PluginCommand("revflood","Hide all, reveal all tiles reachable from cursor position.",revflood,false,
+    commands.push_back(PluginCommand("revflood","Hide all, and reveal tiles reachable from the cursor.",revflood,false,
         "This command hides the whole map. Then, starting from the cursor,\n"
         "reveals all accessible tiles. Allows repairing parma-revealed maps.\n"));
-    commands.push_back(PluginCommand("revforget", "Forget the current reveal data, allowing to use reveal again.",revforget,false,
+    commands.push_back(PluginCommand("revforget", "Forget the current reveal data.",revforget,false,
         "Forget the current reveal data, allowing to use reveal again.\n"));
-    commands.push_back(PluginCommand("nopause","Disable pausing (doesn't affect pause forced by reveal).",nopause,false,
+    commands.push_back(PluginCommand("nopause","Disable manual and automatic pausing.",nopause,false,
         "Disable pausing (doesn't affect pause forced by reveal).\n"
         "Activate with 'nopause 1', deactivate with 'nopause 0'.\n"));
     return CR_OK;

plugins/ruby/ruby.cpp

@@ -99,7 +99,7 @@ DFhackCExport command_result plugin_init ( color_ostream &out, std::vector <Plug
                 df_rubyeval));
 
     commands.push_back(PluginCommand("rb",
-                "Ruby interpreter. Eval() a ruby string (alias for rb_eval).",
+                "Ruby interpreter. Eval() a ruby string.",
                 df_rubyeval));
 
     return CR_OK;

plugins/seedwatch.cpp

@@ -254,7 +254,7 @@ command_result df_seedwatch(color_ostream &out, vector<string>& parameters)
 
 DFhackCExport command_result plugin_init(color_ostream &out, vector<PluginCommand>& commands)
 {
-    commands.push_back(PluginCommand("seedwatch", "Switches cookery based on quantity of seeds, to keep reserves", df_seedwatch));
+    commands.push_back(PluginCommand("seedwatch", "Toggles seed cooking based on quantity available", df_seedwatch));
     // fill in the abbreviations map, with abbreviations for the standard plants
     abbreviations["bs"] = "SLIVER_BARB";
     abbreviations["bt"] = "TUBER_BLOATED";

plugins/stockflow.cpp

@@ -29,7 +29,7 @@ REQUIRE_GLOBAL(world);
 REQUIRE_GLOBAL(ui);
 
 bool fast = false;
-const char *tagline = "Allows the fortress bookkeeper to queue jobs through the manager.";
+const char *tagline = "Allow the bookkeeper to queue manager jobs.";
 const char *usage = (
     "  stockflow enable\n"
     "    Enable the plugin.\n"

plugins/stockpiles/stockpiles.cpp

@@ -85,7 +85,7 @@ DFhackCExport command_result plugin_init ( color_ostream &out, std::vector <Plug
         );
         commands.push_back (
             PluginCommand (
-                "loadstock", "Load settings from a file and apply them to the active stockpile.",
+                "loadstock", "Load and apply stockpile settings from a file.",
                 loadstock, loadstock_guard,
                 "Must be in 'q' mode and have a stockpile selected.\n"
                 "example: 'loadstock food.dfstock' will load the settings from 'food.dfstock'\n"

plugins/strangemood.cpp

@@ -1316,7 +1316,7 @@ command_result df_strangemood (color_ostream &out, vector <string> & parameters)
 
 DFhackCExport command_result plugin_init (color_ostream &out, std::vector<PluginCommand> &commands)
 {
-    commands.push_back(PluginCommand("strangemood", "Force a strange mood to happen.\n", df_strangemood, false,
+    commands.push_back(PluginCommand("strangemood", "Force a strange mood to happen.", df_strangemood, false,
         "Options:\n"
          "  -force         - Ignore standard mood preconditions.\n"
          "  -unit          - Use the selected unit instead of picking one randomly.\n"

plugins/tiletypes.cpp

@@ -58,9 +58,9 @@ DFhackCExport command_result plugin_init ( color_ostream &out, std::vector <Plug
 {
     tiletypes_hist.load("tiletypes.history");
     commands.push_back(PluginCommand("tiletypes", "Paint map tiles freely, similar to liquids.", df_tiletypes, true));
-    commands.push_back(PluginCommand("tiletypes-command", "Run the given commands (seperated by ' ; '; an empty command is the same as run).", df_tiletypes_command));
+    commands.push_back(PluginCommand("tiletypes-command", "Run tiletypes commands (seperated by ' ; ')", df_tiletypes_command));
-    commands.push_back(PluginCommand("tiletypes-here", "Use the last settings from tiletypes, including brush, at cursor location.", df_tiletypes_here));
+    commands.push_back(PluginCommand("tiletypes-here", "Repeat tiletypes command at cursor (with brush)", df_tiletypes_here));
-    commands.push_back(PluginCommand("tiletypes-here-point", "Use the last settings from tiletypes, not including brush, at cursor location.", df_tiletypes_here_point));
+    commands.push_back(PluginCommand("tiletypes-here-point", "Repeat tiletypes command at cursor (without brush)", df_tiletypes_here_point));
     return CR_OK;
 }
 

plugins/workNow.cpp

@@ -29,7 +29,7 @@ DFhackCExport command_result plugin_init(color_ostream& out, std::vector<PluginC
     if (!process_jobs || !process_dig)
         return CR_FAILURE;
 
-    commands.push_back(PluginCommand("workNow", "makes dwarves look for jobs whever they finish one, or every time you pause", workNow, false, "When workNow is active, every time the game pauses, DF will make dwarves perform any appropriate available jobs. This includes when you one step through the game using the pause menu. When workNow is in mode 2, it will make dwarves look for jobs every time a job completes.\n"
+    commands.push_back(PluginCommand("workNow", "Don't allow dwarves to idle if any jobs are available", workNow, false, "When workNow is active, every time the game pauses, DF will make dwarves perform any appropriate available jobs. This includes when you one step through the game using the pause menu. When workNow is in mode 2, it will make dwarves look for jobs every time a job completes.\n"
                 "workNow\n"
                 "  print workNow status\n"
                 "workNow 0\n"

scripts/adaptation.rb

@@ -1,4 +1,4 @@
-# View or set level of cavern adaptation for the selected unit or the whole fort
+# View or set cavern adaptation levels
 # based on removebadthoughts.rb
 =begin
 

scripts/armoks-blessing.lua

@@ -1,7 +1,4 @@
--- Adjust all attributes, personality, age and skills of all dwarves in play
+-- Adjust all attributes of all dwarves to an ideal
--- without arguments, all attributes, age & personalities are adjusted
--- arguments allow for skills to be adjusted as well
--- WARNING: USING THIS SCRIPT WILL ADJUST ALL DWARVES IN PLAY!
 -- by vjek
 --[[=begin
 
@@ -12,6 +9,9 @@ Runs the equivalent of `rejuvenate`, `elevate-physical`, `elevate-mental`, and
 which sets every stat to an ideal - legendary skills, great traits, and
 easy-to-satisfy preferences.
 
+Without arguments, all attributes, age & personalities are adjusted.
+Arguments allow for skills to be adjusted as well.
+
 =end]]
 function rejuvenate(unit)
     if unit==nil then

scripts/autofarm.rb

@@ -1,4 +1,4 @@
-
+# Select crops to plant based on current stocks
 =begin
 
 autofarm

scripts/autolabor-artisans.lua

@@ -1,10 +1,14 @@
--- Executes an autolabor command for each labor where skill level influences output quality.
+-- Run an autolabor command for skill-affected labors.
 
 --[[=begin
 
 autolabor-artisans
 ==================
-Runs `autolabor`, with settings tuned for small but highly skilled workforces.
+Runs an `autolabor` command, for all labors where skill level
+influences output quality.  Examples::
+
+    autolabor-artisans 0 2 3
+    autolabor-artisans disable
 
 =end]]
 local artisan_labors = {

scripts/brainwash.lua

@@ -1,4 +1,4 @@
--- This script will brainwash a dwarf, modifying their personality
+-- Brainwash a dwarf, modifying their personality
 -- usage is:  target a unit in DF, and execute this script in dfhack
 -- by vjek
 --[[=begin

scripts/deterioratefood.rb

@@ -1,4 +1,4 @@
-# Make food and plants decay, and vanish after a few months
+# Food and plants decay, and vanish after a few months
 =begin
 
 deterioratefood

scripts/devel/all-bob.lua

@@ -1,4 +1,4 @@
---all-bob.lua
+-- Changes the first name of all units to "Bob"
 --author expwnent
 --
 --[[=begin

scripts/devel/inject-raws.lua

@@ -1,4 +1,4 @@
--- Injects new reaction, item and building defs into the world.
+-- Inject new raw definitions into the world
 --[[=begin
 
 devel/inject-raws
@@ -9,6 +9,8 @@ This script attempts to inject new raw objects into your
 world. If the injected references do not match the actual
 edited raws, your save will refuse to load, or load but crash.
 
+This script can handle reaction, item and building definitions.
+
 The savegame contains a list of the relevant definition tokens in
 the right order, but all details are read from raws every time.
 This allows just adding stub definitions, and simply saving and

scripts/devel/inspect-screen.lua

@@ -1,4 +1,4 @@
--- Read the tiles from the screen and display info about them.
+-- Read from the screen and display info about the tiles
 --[[=begin
 
 devel/inspect-screen

scripts/devel/list-filters.lua

@@ -1,4 +1,4 @@
--- List input items for the building currently being built.
+-- List input items for the building being built.
 --[[=begin
 
 devel/list-filters

scripts/devel/nuke-items.lua

@@ -1,4 +1,4 @@
--- Deletes ALL items not held by units, buildings or jobs.
+-- Delete ALL items not held by units, buildings or jobs
 --[[=begin
 
 devel/nuke-items

scripts/devel/prepare-save.lua

@@ -1,4 +1,4 @@
--- Prepare the current save for use with devel/find-offsets.
+-- Prepare the current save for devel/find-offsets
 --[[=begin
 
 devel/prepare-save

scripts/devel/scanitemother.rb

@@ -1,4 +1,4 @@
-# list indices in world.item.other[] where current selected item appears
+# list selected item's indices in world.item.other[]
 =begin
 
 devel/scanitemother

scripts/devel/spawn-unit-helper.rb

@@ -1,4 +1,4 @@
-# setup stuff to allow arena creature spawn after a mode change
+# Allow arena creature spawn after a mode change
 
 df.world.arena_spawn.race.clear
 df.world.arena_spawn.caste.clear

scripts/devel/test-perlin.lua

@@ -1,4 +1,4 @@
--- Generates an image using multiple octaves of perlin noise.
+-- Generates an image using perlin noise
 --[[=begin
 
 devel/test-perlin

scripts/digfort.rb

@@ -1,4 +1,4 @@
-# designate an area for digging according to a plan in csv format
+# designate an area based on a '.csv' plan
 =begin
 
 digfort

scripts/elevate-mental.lua

@@ -1,4 +1,4 @@
--- This script will elevate all the mental attributes of a unit
+-- Elevate all the mental attributes of a unit
 -- by vjek
 --[[=begin
 

scripts/elevate-physical.lua

@@ -1,4 +1,4 @@
--- This script will elevate all the physical attributes of a unit
+-- Elevate all the physical attributes of a unit
 -- by vjek
 --[[=begin
 

scripts/fix/blood-del.lua

@@ -1,6 +1,5 @@
---makes it so that civs won't come with barrels full of blood, ichor, or goo
+-- Stop traders bringing blood, ichor, or goo
---author Urist Da Vinci
+--author Urist Da Vinci; edited by expwnent, scamtank
---edited by expwnent, scamtank
 --[[=begin
 
 fix/blood-del

scripts/fix/loyaltycascade.rb

@@ -1,4 +1,4 @@
-# script to fix loyalty cascade, when you order your militia to kill friendly units
+# Cancels a 'loyalty cascade' when citizens are killed
 =begin
 
 fix/loyaltycascade

scripts/fix/population-cap.lua

@@ -1,4 +1,4 @@
--- Communicates current population to mountainhomes to avoid cap overshooting.
+-- Tells mountainhomes your pop. to avoid overshoot
 
 --[[=begin
 

scripts/forum-dwarves.lua

@@ -1,7 +1,5 @@
--- scripts/forum-dwarves.lua
+-- Save a copy of a text screen for the DF forums
--- Save a copy of a text screen for the DF forums.  Use 'forumdwarves help' for more details.
+-- original author: Caldfir; edited by expwnent, Mchl
--- original author: Caldfir
--- edited by expwnent, Mchl
 --[[=begin
 
 forum-dwarves

scripts/full-heal.lua

@@ -1,4 +1,4 @@
---full-heal.lua
+-- Attempts to fully heal the selected unit
 --author Kurik Amudnil, Urist DaVinci
 --edited by expwnent
 

scripts/gaydar.lua

@@ -1,4 +1,4 @@
-local utils = require('utils')
+-- Shows the sexual orientation of units
 --[[=begin
 
 gaydar
@@ -8,6 +8,7 @@ the viability of livestock breeding programs.  Use ``gaydar -help`` for informat
 on available filters for orientation, citizenship, species, etc.
 
 =end]]
+local utils = require('utils')
 
 validArgs = utils.invert({
   'all',

scripts/growcrops.rb

@@ -1,4 +1,4 @@
-# grow crops in farm plots. ex: growcrops helmet_plump 20
+# Instantly grow crops in farm plots
 =begin
 
 growcrops

scripts/gui/advfort_items.lua

@@ -1,4 +1,4 @@
-
+--Does something with items in adventure mode jobs
 --[[=begin
 
 gui/advfort_items

scripts/gui/assign-rack.lua

@@ -1,5 +1,4 @@
--- Assign weapon racks to squads. Requires the weaponrack-unassign patch.
+-- Assign weapon racks to squads (needs binpatch)
-
 --[[=begin
 
 gui/assign-rack

scripts/gui/choose-weapons.lua

@@ -1,4 +1,4 @@
--- Rewrite individual choice weapons into specific types.
+-- Rewrite individual choice weapons to specific types
 --[[=begin
 
 gui/choose-weapons

scripts/gui/clone-uniform.lua

@@ -1,4 +1,4 @@
--- Clone the current uniform template in the military screen.
+-- Clone a uniform template in the military screen
 --[[=begin
 
 gui/clone-uniform

scripts/gui/companion-order.lua

@@ -1,4 +1,4 @@
-
+-- Issue orders to companions in Adventure mode
 --[[=begin
 
 gui/companion-order

scripts/gui/gm-unit.lua

@@ -1,4 +1,4 @@
--- Interface powered (somewhat user friendly) unit editor.
+-- Interface powered, user friendly, unit editor
 
 --[[=begin
 

scripts/gui/guide-path.lua

@@ -1,4 +1,4 @@
--- Show and manipulate the path used by Guide Cart orders.
+-- Show/change the path used by Guide Cart orders
 --[[=begin
 
 gui/guide-path

scripts/hfs-pit.lua

@@ -1,4 +1,4 @@
--- Creates a pit under the target leading straight to the Underworld.  Type '?' for help.
+-- Creates a pit to the Underworld under the target
 -- Based on script by IndigoFenix, @ https://gist.github.com/IndigoFenix/8776696
 --[[=begin
 

scripts/make-legendary.lua

@@ -1,5 +1,4 @@
--- This script will modify a skill or the skills of a single unit
+-- Make a skill or skills of a unit Legendary +5
--- the skill will be increased to 20 (Legendary +5)
 -- by vjek
 --[[=begin
 

scripts/markdown.lua

@@ -1,4 +1,4 @@
--- Save a copy of a text screen in markdown (for reddit among others). Use 'markdown help' for more details.
+-- Save a text screen in markdown (eg for reddit)
 -- This is a derivatiwe work based upon scripts/forum-dwarves.lua by Caldfir and expwnent
 -- Adapted for markdown by Mchl https://github.com/Mchl
 --[[=begin

scripts/migrants-now.lua

@@ -1,4 +1,4 @@
--- Force a migrant wave (only works after hardcoded waves)
+-- Force a migrant wave (only after hardcoded waves)
 --[[=begin
 
 migrants-now

scripts/modtools/add-syndrome.lua

@@ -1,4 +1,4 @@
---modtools/add-syndrome.lua
+-- Add or remove syndromes from units
 --author expwnent
 --[[=begin
 

scripts/modtools/anonymous-script.lua

@@ -1,6 +1,5 @@
---scripts/modtools/anonymous-script.lua
+-- invoke simple lua scripts from strings
 --author expwnent
---a tool for invoking simple lua scripts without putting them in a file first
 --[[=begin
 
 modtools/anonymous-script

scripts/modtools/create-item.lua

@@ -1,6 +1,5 @@
---scripts/modtools/create-item.lua
+-- creates an item of a given type and material
 --author expwnent
---creates an item of a given type and material
 --[[=begin
 
 modtools/create-item

scripts/modtools/create-unit.lua

@@ -1,4 +1,4 @@
--- create-unit.lua
+-- Creates a unit.  Beta; use at own risk.
 -- Originally created by warmist, edited by Putnam for the dragon ball mod to be used in reactions, modified by Dirst for use in The Earth Strikes Back mod, incorporating fixes discovered by Boltgun then Mifiki wrote the bit where it switches to arena mode briefly to do some of the messy work, then Expwnent combined that with the old script to make it function for histfigs
 -- version 0.51
 -- This is a beta version. Use at your own risk.

scripts/modtools/equip-item.lua

@@ -1,4 +1,3 @@
--- modtools/equip-item.lua
 -- equip an item on a unit with a particular body part
 --[[=begin
 

scripts/modtools/force.lua

@@ -1,7 +1,6 @@
--- scripts/modtools/force.lua
+-- Forces an event (caravan, migrants, etc)
 -- author Putnam
 -- edited by expwnent
--- Forces an event.
 --[[=begin
 
 modtools/force

scripts/modtools/interaction-trigger.lua

@@ -1,6 +1,5 @@
---scripts/modtools/interaction-trigger.lua
+-- triggers scripts based on unit interactions
 --author expwnent
---triggers scripts when a unit does a unit interaction on another
 --[[=begin
 
 modtools/interaction-trigger

scripts/modtools/invader-item-destroyer.lua

@@ -1,6 +1,5 @@
---scripts/modtools/invader-item-destroyer.lua
+-- delete invader items when they die
 --author expwnent
---configurably deletes invader items when they die
 --[[=begin
 
 modtools/invader-item-destroyer

scripts/modtools/item-trigger.lua

@@ -1,4 +1,4 @@
---scripts/modtools/attack-trigger.lua
+-- trigger commands based on attacks with certain items
 --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

scripts/modtools/moddable-gods.lua

@@ -1,4 +1,4 @@
---scripts/modtools/moddable-gods.lua
+-- Create gods from the command-line
 --based on moddableGods by Putnam
 --edited by expwnent
 --[[=begin

scripts/modtools/outside-only.lua

@@ -1,6 +1,5 @@
---scripts/modtools/outsideOnly.lua
+-- enables outside only and inside only buildings
 --author expwnent
---enables outside only and inside only buildings
 --[[=begin
 
 modtools/outside-only

scripts/modtools/projectile-trigger.lua

@@ -1,4 +1,4 @@
---scripts/modtools/projectile-trigger.lua
+-- trigger commands when projectiles hit targets
 --author expwnent
 --based on Putnam's projectileExpansion
 --TODO: trigger based on contaminants

scripts/modtools/random-trigger.lua

@@ -1,5 +1,4 @@
---scripts/modtools/random-trigger.lua
+-- triggers random scripts
---triggers random scripts
 --[[=begin
 
 modtools/random-trigger

scripts/modtools/reaction-product-trigger.lua

@@ -1,6 +1,5 @@
--- scripts/modtools/reaction-product-trigger.lua
+-- trigger commands before/after reactions produce items
 -- author expwnent
--- trigger commands just before and after custom reactions produce items
 --@ module = true
 --[[=begin
 

scripts/modtools/reaction-trigger-transition.lua

@@ -1,4 +1,4 @@
--- scripts/modtools/reaction-trigger-transition.lua
+-- help transition from autoSyndrome
 -- author expwnent
 --[[=begin
 

scripts/modtools/reaction-trigger.lua

@@ -1,6 +1,6 @@
--- scripts/modtools/reaction-trigger.lua
+-- trigger commands when custom reactions complete
 -- author expwnent
--- replaces autoSyndrome: trigger commands when custom reactions are completed
+-- replaces autoSyndrome
 --@ module = true
 --[[=begin
 

scripts/modtools/skill-change.lua

@@ -1,4 +1,4 @@
---scripts/modtools/skill-change.lua
+-- Sets or modifies a skill of a unit
 --author expwnent
 --based on skillChange.lua by Putnam
 --TODO: update skill level once experience increases/decreases

scripts/modtools/spawn-flow.lua

@@ -1,6 +1,5 @@
---scripts/modtools/spawn-flow.lua
+-- spawns flows at locations
 --author expwnent
---spawns flows at locations
 --[[=begin
 
 modtools/spawn-flow

scripts/modtools/syndrome-trigger.lua

@@ -1,6 +1,5 @@
---scripts/modtools/syndrome-trigger.lua
+-- triggers scripts when a syndrome is applied
 --author expwnent
---triggers scripts when units are infected with syndromes
 --[[=begin
 
 modtools/syndrome-trigger

scripts/modtools/transform-unit.lua

@@ -1,4 +1,4 @@
---scripts/modtools/transform-unit.lua
+-- Transforms a unit into another unit type
 --author expwnent
 --based on shapechange by Putnam
 --[[=begin

scripts/points.lua

@@ -1,4 +1,4 @@
--- by Meph
+-- Set available points at the embark screen
 -- http://www.bay12forums.com/smf/index.php?topic=135506.msg4925005#msg4925005
 --[[=begin
 

scripts/region-pops.lua

@@ -1,4 +1,4 @@
--- Shows populations of animals in the region, and allows tweaking them.
+-- Show or edit regional plant and animal populations
 --[[=begin
 
 region-pops

scripts/remove-wear.lua

@@ -1,7 +1,5 @@
--- scripts/remove-wear.lua
 -- Resets all items in your fort to 0 wear
--- original author: Laggy
+-- original author: Laggy, edited by expwnent
--- edited by expwnent
 --[[=begin
 
 remove-wear

scripts/repeat.lua

@@ -1,5 +1,5 @@
--- scripts/repeat.lua
+-- repeatedly call a lua script
--- repeatedly calls a lua script, eg "repeat -time 1 months -command cleanowned"; to disable "repeat -cancel cleanowned"
+-- eg "repeat -time 1 months -command cleanowned"; to disable "repeat -cancel cleanowned"
 -- repeat -help for details
 -- author expwnent
 -- vaguely based on a script by Putnam

scripts/show-unit-syndromes.rb

@@ -1,6 +1,5 @@
-# Show syndromes affecting units and the remaining and maximum duration
+# Show syndromes affecting units, including duration
-# original author: drayath
+# original author: drayath, edited by expwnent
-# edited by expwnent
 =begin
 
 show-unit-syndromes

scripts/siren.lua

@@ -1,4 +1,4 @@
--- Wakes up the sleeping, breaks up parties and stops breaks.
+-- Wakes up the sleeping, ends breaks and parties
 --[[=begin
 
 siren

scripts/source.rb

@@ -1,4 +1,4 @@
-# create an infinite magma/water source/drain at the cursor
+# create an infinite source/drain of magma/water
 =begin
 
 source

scripts/starvingdead.rb

@@ -1,4 +1,4 @@
-# Make undead units weaken after one month, and vanish after six
+# Weaken and eventually destroy undead over time
 =begin
 
 starvingdead

scripts/teleport.lua

@@ -1,4 +1,3 @@
--- teleport.lua
 -- teleports a unit to a location
 -- author Putnam
 -- edited by expwnent

scripts/warn-starving.lua

@@ -1,4 +1,4 @@
--- Pauses the game with a warning if a creature is starving, dehydrated, or very drowsy.
+-- Pause and warn if a unit is starving
 -- By Meneth32, PeridexisErrant, Lethosor
 --@ module = true
 --[[=begin

travis/script-in-readme.py

@@ -13,12 +13,25 @@ def expected_cmd(path):
     return fname
 
 
+def check_ls(fname, line):
+    """Check length & existence of leading comment for "ls" builtin command."""
+    line = line.strip()
+    comment = '--' if fname.endswith('.lua') else '#'
+    if line.endswith('=begin') or not line.startswith(comment):
+        print('Error: no leading comment in ' + fname)
+        return 1
+    if len(line.replace(comment, '').strip()) > 53:
+        print('Error: leading comment too long in ' + fname)
+        return 1
+    return 0
+
+
 def check_file(fname):
     errors, doclines = 0, []
     with open(fname, errors='ignore') as f:
-        for l in f.readlines():
+        lines = f.readlines()
-            if not l.strip():
+        errors += check_ls(fname, lines[0])
-                continue
+        for l in lines:
             if doclines or l.strip().endswith('=begin'):
                 doclines.append(l.rstrip())
             if l.startswith('=end'):
@@ -29,7 +42,7 @@ def check_file(fname):
             else:
                 print('Error: no documentation in: ' + fname)
             return 1
-    title, underline = doclines[1], doclines[2]
+    title, underline = [d for d in doclines if d and '=begin' not in d][:2]
     if underline != '=' * len(title):
         print('Error: title/underline mismatch:', fname, title, underline)
         errors += 1