diff --git a/docs/Contributing.rst b/docs/Contributing.rst index 809929df6..d29c4acef 100644 --- a/docs/Contributing.rst +++ b/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 diff --git a/docs/Plugins.rst b/docs/Plugins.rst index 89a6cc5f8..4e1886e8d 100644 --- a/docs/Plugins.rst +++ b/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 `_. At present, -only buildings constructed of an item with the same name as the building +The syntax of the file itself is similar to `digfort` or :forums:`quickfort <35931>`. +At present, 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 `, 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. diff --git a/plugins/autochop.cpp b/plugins/autochop.cpp index 1d972c588..73a3da24e 100644 --- a/plugins/autochop.cpp +++ b/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 &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" )); diff --git a/plugins/automelt.cpp b/plugins/automelt.cpp index 0aacce233..b4c93e15f 100644 --- a/plugins/automelt.cpp +++ b/plugins/automelt.cpp @@ -299,7 +299,7 @@ DFhackCExport command_result plugin_init ( color_ostream &out, std::vector & parameters) DFhackCExport command_result plugin_init ( color_ostream &out, std::vector &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" diff --git a/plugins/cursecheck.cpp b/plugins/cursecheck.cpp index e33c85855..82404b288 100644 --- a/plugins/cursecheck.cpp +++ b/plugins/cursecheck.cpp @@ -58,7 +58,7 @@ command_result cursecheck (color_ostream &out, vector & parameters); DFhackCExport command_result plugin_init ( color_ostream &out, std::vector &commands) { commands.push_back(PluginCommand("cursecheck", - "Checks for cursed creatures (vampires, necromancers, zombies, ...).", + "Check for cursed creatures (undead, necromancers...)", cursecheck, false )); return CR_OK; } diff --git a/plugins/deramp.cpp b/plugins/deramp.cpp index dc2651db7..f0171dabc 100644 --- a/plugins/deramp.cpp +++ b/plugins/deramp.cpp @@ -83,7 +83,7 @@ command_result df_deramp (color_ostream &out, vector & parameters) DFhackCExport command_result plugin_init ( color_ostream &out, std::vector &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" diff --git a/plugins/devel/kittens.cpp b/plugins/devel/kittens.cpp index fd4ec268d..6317a0a39 100644 --- a/plugins/devel/kittens.cpp +++ b/plugins/devel/kittens.cpp @@ -42,7 +42,7 @@ DFHACK_PLUGIN("kittens"); DFhackCExport command_result plugin_init ( color_ostream &out, std::vector &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)); diff --git a/plugins/devel/memview.cpp b/plugins/devel/memview.cpp index d61775a38..07158babc 100644 --- a/plugins/devel/memview.cpp +++ b/plugins/devel/memview.cpp @@ -36,7 +36,7 @@ DFHACK_PLUGIN("memview"); DFhackCExport command_result plugin_init (color_ostream &out, std::vector &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; diff --git a/plugins/devel/rprobe.cpp b/plugins/devel/rprobe.cpp index f20222d8a..71da40600 100644 --- a/plugins/devel/rprobe.cpp +++ b/plugins/devel/rprobe.cpp @@ -45,7 +45,7 @@ DFHACK_PLUGIN("rprobe"); DFhackCExport command_result plugin_init ( color_ostream &out, std::vector &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" )); diff --git a/plugins/dig.cpp b/plugins/dig.cpp index 0d49535ad..5404f2f2d 100644 --- a/plugins/dig.cpp +++ b/plugins/dig.cpp @@ -55,8 +55,8 @@ DFhackCExport command_result plugin_init ( color_ostream &out, std::vector &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" diff --git a/plugins/filltraffic.cpp b/plugins/filltraffic.cpp index d78e07046..0f9a7bb6f 100644 --- a/plugins/filltraffic.cpp +++ b/plugins/filltraffic.cpp @@ -44,7 +44,7 @@ DFHACK_PLUGIN("filltraffic"); DFhackCExport command_result plugin_init ( color_ostream &out, std::vector &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" diff --git a/plugins/follow.cpp b/plugins/follow.cpp index 323b0a498..7b8ad3906 100644 --- a/plugins/follow.cpp +++ b/plugins/follow.cpp @@ -29,7 +29,7 @@ uint8_t prevMenuWidth; DFhackCExport command_result plugin_init ( color_ostream &out, std::vector &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" diff --git a/plugins/forceequip.cpp b/plugins/forceequip.cpp index 1f1eb1ce6..da6f1aff4 100644 --- a/plugins/forceequip.cpp +++ b/plugins/forceequip.cpp @@ -216,7 +216,7 @@ const string forceequip_help = DFhackCExport command_result plugin_init ( color_ostream &out, vector &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() )); diff --git a/plugins/fortplan.cpp b/plugins/fortplan.cpp index 4187f2d0a..a1934c4ab 100644 --- a/plugins/fortplan.cpp +++ b/plugins/fortplan.cpp @@ -51,7 +51,7 @@ public: std::vector buildings; DFhackCExport command_result plugin_init ( color_ostream &out, vector &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")); diff --git a/plugins/getplants.cpp b/plugins/getplants.cpp index ed3272265..87fc35960 100644 --- a/plugins/getplants.cpp +++ b/plugins/getplants.cpp @@ -152,7 +152,7 @@ command_result df_getplants (color_ostream &out, vector & parameters) DFhackCExport command_result plugin_init ( color_ostream &out, vector &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" diff --git a/plugins/hotkeys.cpp b/plugins/hotkeys.cpp index d7139dd96..6ec281143 100644 --- a/plugins/hotkeys.cpp +++ b/plugins/hotkeys.cpp @@ -354,7 +354,7 @@ DFhackCExport command_result plugin_init ( color_ostream &out, std::vector & params) DFhackCExport command_result plugin_init ( color_ostream &out, std::vector &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; } diff --git a/plugins/petcapRemover.cpp b/plugins/petcapRemover.cpp index ee33f6670..c059db4c3 100644 --- a/plugins/petcapRemover.cpp +++ b/plugins/petcapRemover.cpp @@ -36,7 +36,7 @@ DFhackCExport command_result plugin_init ( color_ostream &out, std::vector 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); - } - - if(hasBuilding) - for (int i = 0; i < df::global::world->buildings.all.size(); i++) - { - + switch (designation.bits.dig) + { + case df::enums::tile_dig_designation::No: + 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); diff --git a/plugins/resume.cpp b/plugins/resume.cpp index 56a43b14e..8553fd4f0 100644 --- a/plugins/resume.cpp +++ b/plugins/resume.cpp @@ -298,7 +298,7 @@ DFhackCExport command_result plugin_init ( color_ostream &out, std::vector & params); DFhackCExport command_result plugin_init ( color_ostream &out, vector &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 & parameters) DFhackCExport command_result plugin_init(color_ostream &out, vector& 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"; diff --git a/plugins/stockflow.cpp b/plugins/stockflow.cpp index 15a013dea..ff87bdddc 100644 --- a/plugins/stockflow.cpp +++ b/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" diff --git a/plugins/stockpiles/stockpiles.cpp b/plugins/stockpiles/stockpiles.cpp index bfba7e1e4..3cd2cb31a 100644 --- a/plugins/stockpiles/stockpiles.cpp +++ b/plugins/stockpiles/stockpiles.cpp @@ -85,7 +85,7 @@ DFhackCExport command_result plugin_init ( color_ostream &out, std::vector & parameters) DFhackCExport command_result plugin_init (color_ostream &out, std::vector &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" diff --git a/plugins/tiletypes.cpp b/plugins/tiletypes.cpp index 1a249825c..ae5362e15 100644 --- a/plugins/tiletypes.cpp +++ b/plugins/tiletypes.cpp @@ -58,9 +58,9 @@ DFhackCExport command_result plugin_init ( color_ostream &out, std::vector 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(): - if not l.strip(): - continue + lines = f.readlines() + errors += check_ls(fname, lines[0]) + 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