From 19a49059337b56bfcea47e4c4f3a364c91ebee79 Mon Sep 17 00:00:00 2001 From: myk002 Date: Fri, 22 Jul 2022 16:42:36 -0700 Subject: [PATCH] update docs for "c" plugins --- docs/plugins/changeitem.rst | 5 ++- docs/plugins/changelayer.rst | 9 +++-- docs/plugins/changevein.rst | 9 +++-- docs/plugins/clean.rst | 37 ------------------ docs/plugins/cleanconst.rst | 11 +++--- docs/plugins/cleaners.rst | 46 +++++++++++++++++++++++ docs/plugins/cleanowned.rst | 11 +++--- docs/plugins/command-prompt.rst | 19 ++++++---- docs/plugins/confirm.rst | 22 +++++++---- docs/plugins/createitem.rst | 66 +++++++++++++++++---------------- docs/plugins/cromulate.rst | 14 ++++--- docs/plugins/cursecheck.rst | 66 ++++++++++++++++++++------------- docs/plugins/spotclean.rst | 14 ------- plugins/changelayer.cpp | 2 +- plugins/changevein.cpp | 2 +- plugins/cleaners.cpp | 4 +- plugins/command-prompt.cpp | 9 ++--- plugins/confirm.cpp | 9 +---- plugins/createitem.cpp | 25 ++----------- plugins/cromulate.cpp | 4 +- plugins/cursecheck.cpp | 5 ++- 21 files changed, 199 insertions(+), 190 deletions(-) delete mode 100644 docs/plugins/clean.rst create mode 100644 docs/plugins/cleaners.rst delete mode 100644 docs/plugins/spotclean.rst diff --git a/docs/plugins/changeitem.rst b/docs/plugins/changeitem.rst index 0a841511c..5dd537a60 100644 --- a/docs/plugins/changeitem.rst +++ b/docs/plugins/changeitem.rst @@ -4,8 +4,9 @@ changeitem Tags: :dfhack-keybind: -Allows changing item material and base quality. By default, a change is only -allowed if the existing and desired item materials are of the same subtype +:index:`Change item material and base quality. +` By default, a change is +only allowed if the existing and desired item materials are of the same subtype (for example wood -> wood, stone -> stone, etc). But since some transformations work pretty well and may be desired you can override this with ``force``. Note that forced changes can possibly result in items that crafters and haulers diff --git a/docs/plugins/changelayer.rst b/docs/plugins/changelayer.rst index 535409e90..76d631cdf 100644 --- a/docs/plugins/changelayer.rst +++ b/docs/plugins/changelayer.rst @@ -4,10 +4,11 @@ changelayer Tags: :dfhack-keybind: -Change the material of an entire geology layer. Note that one layer can stretch -across many z-levels, and changes to the geology layer will affect all -surrounding regions, not just your embark! Mineral veins and gem clusters will -not be affected. Use `changevein` if you want to modify those. +:index:`Change the material of an entire geology layer. +` Note that one +layer can stretch across many z-levels, and changes to the geology layer will +affect all surrounding regions, not just your embark! Mineral veins and gem +clusters will not be affected. Use `changevein` if you want to modify those. tl;dr: You will end up with changing large areas in one go, especially if you use it in lower z levels. Use this command with care! diff --git a/docs/plugins/changevein.rst b/docs/plugins/changevein.rst index f4871772e..7de94a3f0 100644 --- a/docs/plugins/changevein.rst +++ b/docs/plugins/changevein.rst @@ -4,10 +4,11 @@ changevein Tags: :dfhack-keybind: -Changes the material of a mineral inclusion. You can change it to any incorganic -material RAW id. Note that this command only affects tiles within the current -16x16 block - for large veins and clusters, you will need to use this command -multiple times. +:index:`Change the material of a mineral inclusion. +` You can change it to +any incorganic material RAW id. Note that this command only affects tiles within +the current 16x16 block - for large veins and clusters, you will need to use +this command multiple times. You can use the `probe` command to discover the material RAW ids for existing veins that you want to duplicate. diff --git a/docs/plugins/clean.rst b/docs/plugins/clean.rst deleted file mode 100644 index 54421ce91..000000000 --- a/docs/plugins/clean.rst +++ /dev/null @@ -1,37 +0,0 @@ -clean -===== - -Tags: -:dfhack-keybind: - -Removes contaminants from tiles, items, and units. More specifically, it -cleans all the splatter that get scattered all over the map and that clings to -your items and units. In an old fortress, this can significantly reduce FPS lag. -It can also spoil your !!FUN!!, so think before you use it. - -Usage:: - - clean all|map|items|units|plants [] - -By default, cleaning the map leaves mud and snow alone. Note that cleaning units -includes hostiles, and that cleaning items removes poisons from weapons. - -Options -------- - -When cleaning the map, you can specify extra options for extra cleaning: - -- ``mud`` - Also remove mud. -- ``item`` - Also remove item spatter, like fallen leaves and flowers. -- ``snow`` - Also remove snow coverings. - -Examples --------- - -- ``clean all`` - Clean everything that can be cleaned (except mud and snow). -- ``clean all mud item snow`` - Removes all spatter, including mud, leaves, and snow from map tiles. diff --git a/docs/plugins/cleanconst.rst b/docs/plugins/cleanconst.rst index c34bac6bf..286069b63 100644 --- a/docs/plugins/cleanconst.rst +++ b/docs/plugins/cleanconst.rst @@ -2,12 +2,13 @@ cleanconst ========== Tags: -:dfhack-keybind: +:dfhack-keybind:`cleanconst` -Cleans up construction materials. This tool alters all constructions on the map -so that they spawn their building component when they are disassembled, allowing -their actual build items to be safely deleted. This can improve FPS when you -have many constructions on the map. +:index:`Cleans up construction materials. +` This tool alters all +constructions on the map so that they spawn their building component when they +are disassembled, allowing their actual build items to be safely deleted. This +can improve FPS when you have many constructions on the map. Usage:: diff --git a/docs/plugins/cleaners.rst b/docs/plugins/cleaners.rst new file mode 100644 index 000000000..b290a73a4 --- /dev/null +++ b/docs/plugins/cleaners.rst @@ -0,0 +1,46 @@ +cleaners +======== + +Tags: +:dfhack-keybind:`clean` +:dfhack-keybind:`spotclean` + +:index:`Removes contaminants from tiles, items, and units. +` More specifically, +it cleans all the splatter that get scattered all over the map and that clings +to your items and units. In an old fortress, this can significantly reduce FPS +lag. It can also spoil your !!FUN!!, so think before you use it. + +Usage:: + + clean all|map|items|units|plants [] + spotclean + +By default, cleaning the map leaves mud and snow alone. Note that cleaning units +includes hostiles, and that cleaning items removes poisons from weapons. + +``spotclean`` works like ``clean map snow mud``, +:index:`removing all contaminants from the tile under the cursor. +` This is ideal +if you just want to clean a specific tile but don't want the `clean` command to +remove all the glorious blood from your entranceway. + +Options +------- + +When cleaning the map, you can specify extra options for extra cleaning: + +- ``mud`` + Also remove mud. +- ``item`` + Also remove item spatter, like fallen leaves and flowers. +- ``snow`` + Also remove snow coverings. + +Examples +-------- + +- ``clean all`` + Clean everything that can be cleaned (except mud and snow). +- ``clean all mud item snow`` + Removes all spatter, including mud, leaves, and snow from map tiles. diff --git a/docs/plugins/cleanowned.rst b/docs/plugins/cleanowned.rst index 27e4806a2..e827989c9 100644 --- a/docs/plugins/cleanowned.rst +++ b/docs/plugins/cleanowned.rst @@ -2,12 +2,13 @@ cleanowned ========== Tags: -:dfhack-keybind: +:dfhack-keybind:`cleanowned` -Confiscates and dumps garbage owned by dwarves. This tool gets dwarves to give -up ownership of scattered items and items with heavy wear and then marks those -items for dumping. Now you can finally get your dwarves to give up their rotten -food and tattered loincloths and go get new ones! +:index:`Confiscates and dumps garbage owned by dwarves. +` This tool gets +dwarves to give up ownership of scattered items and items with heavy wear and +then marks those items for dumping. Now you can finally get your dwarves to give +up their rotten food and tattered loincloths and go get new ones! Usage:: diff --git a/docs/plugins/command-prompt.rst b/docs/plugins/command-prompt.rst index 061b405ef..6e3d2a829 100644 --- a/docs/plugins/command-prompt.rst +++ b/docs/plugins/command-prompt.rst @@ -1,16 +1,21 @@ command-prompt ============== -An in-game DFHack terminal, where you can enter other commands. +Tags: :dfhack-keybind:`command-prompt` -Usage: ``command-prompt [entry]`` +:index:`An in-game DFHack terminal, where you can enter other commands. +` -If called with an entry, it starts with that text filled in. -Most useful for developers, who can set a keybinding to open -a laungage interpreter for lua or Ruby by starting with the -`:lua ` or `:rb ` commands. +Usage:: -Otherwise somewhat similar to `gui/quickcmd`. + command-prompt [entry] + +If called with parameters, it starts with that text in the command edit area. +This is most useful for developers, who can set a keybinding to open a laungage +interpreter for lua or Ruby by starting with the `:lua ` or `:rb ` +portions of the command already filled in. + +Also see `gui/quickcmd` for a different take on running commands from the UI. .. image:: ../images/command-prompt.png diff --git a/docs/plugins/confirm.rst b/docs/plugins/confirm.rst index c7fb89bb0..25cc04956 100644 --- a/docs/plugins/confirm.rst +++ b/docs/plugins/confirm.rst @@ -1,12 +1,20 @@ confirm ======= -Implements several confirmation dialogs for potentially destructive actions -(for example, seizing goods from traders or deleting hauling routes). + +Tags: +:dfhack-keybind:`confirm` + +:index:`Adds confirmation dialogs for destructive actions. +` Now you can get +the chance to avoid seizing goods from traders or deleting a hauling route in +case you hit the key accidentally. Usage: -:enable confirm: Enable all confirmations; alias ``confirm enable all``. - Replace with ``disable`` to disable. -:confirm help: List available confirmation dialogues. -:confirm enable option1 [option2...]: - Enable (or disable) specific confirmation dialogues. +- ``enable confirm``, ``confirm enable all`` + Enable all confirmation options. Replace with ``disable`` to disable all. +- ``confirm enable option1 [option2...]`` + Enable (or ``disable``) specific confirmation dialogs. + +When run without parameters, ``confirm`` will report which confirmation dialogs +are currently enabled. diff --git a/docs/plugins/createitem.rst b/docs/plugins/createitem.rst index f37154f80..13ecc2e58 100644 --- a/docs/plugins/createitem.rst +++ b/docs/plugins/createitem.rst @@ -1,48 +1,52 @@ createitem ========== -Allows creating new items of arbitrary types and made of arbitrary materials. A -unit must be selected in-game to use this command. By default, items created are -spawned at the feet of the selected unit. -Specify the item and material information as you would indicate them in -custom reaction raws, with the following differences: +Tags: +:dfhack-keybind:`createitem` + +:index:`Create arbitrary items. ` You can +create new items of any type and made of any material. A unit must be selected +in-game to use this command. By default, items created are spawned at the feet +of the selected unit. + +Specify the item and material information as you would indicate them in custom +reaction raws, with the following differences: * Separate the item and material with a space rather than a colon * If the item has no subtype, the ``:NONE`` can be omitted -* If the item is ``REMAINS``, ``FISH``, ``FISH_RAW``, ``VERMIN``, ``PET``, or ``EGG``, - specify a ``CREATURE:CASTE`` pair instead of a material token. +* If the item is ``REMAINS``, ``FISH``, ``FISH_RAW``, ``VERMIN``, ``PET``, or + ``EGG``, then specify a ``CREATURE:CASTE`` pair instead of a material token. * If the item is a ``PLANT_GROWTH``, specify a ``PLANT_ID:GROWTH_ID`` pair instead of a material token. Corpses, body parts, and prepared meals cannot be created using this tool. -To obtain the item and material tokens of an existing item, run -``createitem inspect``. Its output can be passed directly as arguments to -``createitem`` to create new matching items, as long as the item type is -supported. - -Examples: - -* Create 2 pairs of steel gauntlets:: +Usage: - createitem GLOVES:ITEM_GLOVES_GAUNTLETS INORGANIC:STEEL 2 +- ``createitem []`` + Create copies (default is 1) of the specified item made out of the + specified material. +- ``createitem inspect`` + Obtain the item and material tokens of an existing item. Its output can be + used directly as arguments to ``createitem`` to create new matching items + (as long as the item type is supported). +- ``createitem floor|item|building`` + Subsequently created items will be placed on the floor beneath the selected + unit's, inside the selected item, or as part of the selected building. -* Create tower-cap logs:: +.. note:: - createitem WOOD PLANT_MAT:TOWER_CAP:WOOD + ``createitem building`` is good for loading traps, but if you use it with + workshops, you will have to deconstruct the workshop to access the item. -* Create bilberries:: - - createitem PLANT_GROWTH BILBERRY:FRUIT - -For more examples, :wiki:`see this wiki page `. - -To change where new items are placed, first run the command with a -destination type while an appropriate destination is selected. +Examples: -Options: +- ``createitem GLOVES:ITEM_GLOVES_GAUNTLETS INORGANIC:STEEL 2`` + Create 2 pairs of steel gauntlets (that is, 2 left gauntlets and 2 right + gauntlets). +- ``createitem WOOD PLANT_MAT:TOWER_CAP:WOOD 100`` + Create 100 tower-cap logs. +- ``createitem PLANT_GROWTH BILBERRY:FRUIT`` + Create a single bilberry. -:floor: Subsequent items will be placed on the floor beneath the selected unit's feet. -:item: Subsequent items will be stored inside the currently selected item. -:building: Subsequent items will become part of the currently selected building. - Good for loading traps; do not use with workshops (or deconstruct to use the item). +For more examples, :wiki:`the wiki `. diff --git a/docs/plugins/cromulate.rst b/docs/plugins/cromulate.rst index ca07ae0ca..b025fe877 100644 --- a/docs/plugins/cromulate.rst +++ b/docs/plugins/cromulate.rst @@ -1,12 +1,14 @@ cromulate ========= -Tags: productivity, unit, adventure +Tags: `tag/productivity`, `tag/unit`, `tag/adventure` :dfhack-keybind:`cromulate` -Collects all widgets into a frobozz electric cromufiler. You might want to do -this if you discover that your widgets have become decromulated. It is safe to -run this command periodically even if you are unsure if that's the case. +:index:`Collects all widgets into a frobozz electric cromufiler. +` You might +want to do this if you discover that your widgets have become decromulated. It +is safe to run this command periodically even if you are unsure if that's the +case. Usage:: @@ -18,9 +20,9 @@ collect those under the cursor. Options: -:``-d``, ``--destroy``: +- ``-d``, ``--destroy`` Destroy the widgets instead of collecting them into the cromufiler. -:``-q``, ``--quiet``: +- ``-q``, ``--quiet`` Don't display any informational output. Errors will still be printed to the console. diff --git a/docs/plugins/cursecheck.rst b/docs/plugins/cursecheck.rst index 1bf1803fa..79da6d621 100644 --- a/docs/plugins/cursecheck.rst +++ b/docs/plugins/cursecheck.rst @@ -1,42 +1,56 @@ cursecheck ========== -Checks a single map tile or the whole map/world for cursed creatures (ghosts, -vampires, necromancers, werebeasts, zombies). -With an active in-game cursor only the selected tile will be observed. -Without a cursor the whole map will be checked. +Tags: +:dfhack-keybind:`cursecheck` -By default cursed creatures will be only counted in case you just want to find -out if you have any of them running around in your fort. Dead and passive -creatures (ghosts who were put to rest, killed vampires, ...) are ignored. -Undead skeletons, corpses, bodyparts and the like are all thrown into the curse -category "zombie". Anonymous zombies and resurrected body parts will show -as "unnamed creature". +:index:`Check for cursed creatures. ` +This command checks a single map tile (or the whole map/world) for cursed +creatures (ghosts, vampires, necromancers, werebeasts, zombies, etc.). + +With an active in-game cursor, only the selected tile will be checked. Without a +cursor, the whole map will be checked. + +By default, you will just see the count of cursed creatures in case you just +want to find out if you have any of them running around in your fort. Dead and +passive creatures (ghosts who were put to rest, killed vampires, etc.) are +ignored. Undead skeletons, corpses, bodyparts and the like are all thrown into +the curse category "zombie". Anonymous zombies and resurrected body parts will +show as "unnamed creature". + +Usage:: + + cursecheck [] Options: -:detail: Print full name, date of birth, date of curse and some status - info (some vampires might use fake identities in-game, though). -:ids: Print the creature and race IDs. -:nick: Set the type of curse as nickname (does not always show up - in-game, some vamps don't like nicknames). -:all: Include dead and passive cursed creatures (can result in a quite - long list after having FUN with necromancers). -:verbose: Print all curse tags (if you really want to know it all). +- ``detail`` + Print full name, date of birth, date of curse, and some status info (some + vampires might use fake identities in-game, though). +- ``nick`` + Set the type of curse as nickname (does not always show up in-game; some + vamps don't like nicknames). +- ``ids`` + Print the creature and race IDs. +- ``all`` + Include dead and passive cursed creatures (this can result in quite a long + list after having !!FUN!! with necromancers). +- ``verbose`` + Print all curse tags (if you really want to know it all). Examples: -``cursecheck detail all`` - Give detailed info about all cursed creatures including deceased ones (no - in-game cursor). -``cursecheck nick`` - Give a nickname all living/active cursed creatures on the map(no in-game - cursor). +- ``cursecheck`` + Display a count of cursed creatures on the map (or under the cursor). +- ``cursecheck detail all`` + Give detailed info about all cursed creatures including deceased ones. +- ``cursecheck nick`` + Give a nickname all living/active cursed creatures. .. note:: If you do a full search (with the option "all") former ghosts will show up with the cursetype "unknown" because their ghostly flag is not set. - Please report any living/active creatures with cursetype "unknown" - - this is most likely with mods which introduce new types of curses. + If you see any living/active creatures with a cursetype of "unknown", then + it is most likely a new type of curse introduced by a mod. diff --git a/docs/plugins/spotclean.rst b/docs/plugins/spotclean.rst deleted file mode 100644 index dcad047a4..000000000 --- a/docs/plugins/spotclean.rst +++ /dev/null @@ -1,14 +0,0 @@ -spotclean -========= - -Tags: -:dfhack-keybind: - -Cleans a map tile of contaminants and spatter. It works like -``clean map snow mud``, but only for the tile under the cursor. Ideal if you -just want to clean a specific tile but don't want the `clean` command to remove -all the glorious blood from your entranceway. - -Usage:: - - spotclean diff --git a/plugins/changelayer.cpp b/plugins/changelayer.cpp index 347f29b95..7520ac932 100644 --- a/plugins/changelayer.cpp +++ b/plugins/changelayer.cpp @@ -37,7 +37,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("changevein", - "Changes the material of a mineral inclusion.", + "Change the material of a mineral inclusion.", df_changevein)); return CR_OK; } diff --git a/plugins/cleaners.cpp b/plugins/cleaners.cpp index 7389488f1..00075e9d7 100644 --- a/plugins/cleaners.cpp +++ b/plugins/cleaners.cpp @@ -242,11 +242,11 @@ DFhackCExport command_result plugin_init ( color_ostream &out, std::vector &commands) { commands.push_back(PluginCommand( - "command-prompt", "Shows a command prompt on window.", - show_prompt, hotkey_allow_all, - "command-prompt [entry] - shows a cmd prompt in df window." - " Entry is used for default prefix (e.g. ':lua')" - )); + "command-prompt", + "An in-game DFHack terminal.", + show_prompt, + hotkey_allow_all)); return CR_OK; } diff --git a/plugins/confirm.cpp b/plugins/confirm.cpp index 32da4e1f8..5cef6376f 100644 --- a/plugins/confirm.cpp +++ b/plugins/confirm.cpp @@ -547,13 +547,8 @@ DFhackCExport command_result plugin_init (color_ostream &out, vector & parameters); DFhackCExport command_result plugin_init (color_ostream &out, std::vector &commands) { - commands.push_back(PluginCommand("createitem", "Create arbitrary items.", df_createitem, false, - "Syntax: createitem [count]\n" - " - Item token for what you wish to create, as specified in custom\n" - " reactions. If the item has no subtype, omit the :NONE.\n" - " - The material you want the item to be made of, as specified\n" - " in custom reactions. For REMAINS, FISH, FISH_RAW, VERMIN,\n" - " PET, and EGG, replace this with a creature ID and caste.\n" - " For PLANT_GROWTH, replace this with a plant ID and growth ID.\n" - " [count] - How many of the item you wish to create.\n" - "\n" - "To obtain the item and material of an existing item, run \n" - "'createitem inspect' with that item selected in-game.\n" - "\n" - "To use this command, you must select which unit will create the items.\n" - "By default, items created will be placed at that unit's feet.\n" - "To change this, run 'createitem '.\n" - "Valid destinations:\n" - "* floor - Place items on floor beneath maker's feet.\n" - "* item - Place items inside selected container.\n" - "* building - Place items inside selected building.\n" - )); + commands.push_back( + PluginCommand("createitem", + "Create arbitrary items.", + df_createitem)); return CR_OK; } diff --git a/plugins/cromulate.cpp b/plugins/cromulate.cpp index 9f7fdb9f9..7ed9ed115 100644 --- a/plugins/cromulate.cpp +++ b/plugins/cromulate.cpp @@ -13,9 +13,7 @@ command_result cromulate (color_ostream &out, std::vector & parame DFhackCExport command_result plugin_init (color_ostream &out, std::vector &commands) { commands.push_back(PluginCommand("cromulate", "in-cpp plugin short desc", //to use one line in the ``[DFHack]# ls`` output - cromulate, - false, - "in-cpp plugin long help")); + cromulate)); return CR_OK; } diff --git a/plugins/cursecheck.cpp b/plugins/cursecheck.cpp index d20c645ab..007c81228 100644 --- a/plugins/cursecheck.cpp +++ b/plugins/cursecheck.cpp @@ -79,9 +79,10 @@ command_result cursecheck (color_ostream &out, vector & parameters); DFhackCExport command_result plugin_init ( color_ostream &out, std::vector &commands) { - commands.push_back(PluginCommand("cursecheck", + commands.push_back(PluginCommand( + "cursecheck", "Check for cursed creatures (undead, necromancers...)", - cursecheck, false )); + cursecheck)); return CR_OK; }