update docs for "c" plugins

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
+:index:`Change item material and base quality.
-allowed if the existing and desired item materials are of the same subtype
+<changeitem; 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

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
+:index:`Change the material of an entire geology layer.
-across many z-levels, and changes to the geology layer will affect all
+<changelayer; Change the material of an entire geology layer.>` Note that one
-surrounding regions, not just your embark! Mineral veins and gem clusters will
+layer can stretch across many z-levels, and changes to the geology layer will
-not be affected. Use `changevein` if you want to modify those.
+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!

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
+:index:`Change the material of a mineral inclusion.
-material RAW id. Note that this command only affects tiles within the current
+<changevein; Change the material of a mineral inclusion.>` You can change it to
-16x16 block - for large veins and clusters, you will need to use this command
+any incorganic material RAW id. Note that this command only affects tiles within
-multiple times.
+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.

docs/plugins/clean.rst

@@ -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 [<options>]
-
-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.

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
+:index:`Cleans up construction materials.
-so that they spawn their building component when they are disassembled, allowing
+<cleanconst; Cleans up construction materials.>` This tool alters all
-their actual build items to be safely deleted. This can improve FPS when you
+constructions on the map so that they spawn their building component when they
-have many constructions on the map.
+are disassembled, allowing their actual build items to be safely deleted. This
+can improve FPS when you have many constructions on the map.
 
 Usage::
 

docs/plugins/cleaners.rst

@@ -0,0 +1,46 @@
+cleaners
+========
+
+Tags:
+:dfhack-keybind:`clean`
+:dfhack-keybind:`spotclean`
+
+:index:`Removes contaminants from tiles, items, and units.
+<clean; 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 [<options>]
+    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.
+<clean; Remove 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.

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
+:index:`Confiscates and dumps garbage owned by dwarves.
-up ownership of scattered items and items with heavy wear and then marks those
+<cleanowned; Confiscates and dumps garbage owned by dwarves.>` This tool gets
-items for dumping. Now you can finally get your dwarves to give up their rotten
+dwarves to give up ownership of scattered items and items with heavy wear and
-food and tattered loincloths and go get new ones!
+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::
 

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.
+<command-prompt; An in-game DFHack terminal, where you can enter other commands.>`
 
-If called with an entry, it starts with that text filled in.
+Usage::
-Most useful for developers, who can set a keybinding to open
-a laungage interpreter for lua or Ruby by starting with the
-`:lua <lua>` or `:rb <rb>` commands.
 
-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 <lua>` or `:rb <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

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.
+<confirm; 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``.
+- ``enable confirm``, ``confirm enable all``
-                    Replace with ``disable`` to disable.
+    Enable all confirmation options. Replace with ``disable`` to disable all.
-:confirm help:      List available confirmation dialogues.
+- ``confirm enable option1 [option2...]``
-:confirm enable option1 [option2...]:
+    Enable (or ``disable``) specific confirmation dialogs.
-                    Enable (or disable) specific confirmation dialogues.
+
+When run without parameters, ``confirm`` will report which confirmation dialogs
+are currently enabled.

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
+Tags:
-custom reaction raws, with the following differences:
+:dfhack-keybind:`createitem`
+
+:index:`Create arbitrary items. <createitem; 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``,
+* If the item is ``REMAINS``, ``FISH``, ``FISH_RAW``, ``VERMIN``, ``PET``, or
-  specify a ``CREATURE:CASTE`` pair instead of a material token.
+  ``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
+Usage:
-``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::
 
-    createitem GLOVES:ITEM_GLOVES_GAUNTLETS INORGANIC:STEEL 2
+- ``createitem <item> <material> [<count>]``
+    Create <count> 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::
+Examples:
-
-    createitem PLANT_GROWTH BILBERRY:FRUIT
-
-For more examples, :wiki:`see this wiki page <Utility:DFHack/createitem>`.
-
-To change where new items are placed, first run the command with a
-destination type while an appropriate destination is selected.
 
-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.
+For more examples, :wiki:`the wiki <Utility:DFHack/createitem>`.
-: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).

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
+:index:`Collects all widgets into a frobozz electric cromufiler.
-this if you discover that your widgets have become decromulated. It is safe to
+<cromulate; Collects all widgets into a frobozz electric cromufiler.>` You might
-run this command periodically even if you are unsure if that's the case.
+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.
 

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.
+Tags:
-Without a cursor the whole map will be checked.
+:dfhack-keybind:`cursecheck`
 
-By default cursed creatures will be only counted in case you just want to find
+:index:`Check for cursed creatures. <cursecheck; Check for cursed creatures.>`
-out if you have any of them running around in your fort. Dead and passive
+This command checks a single map tile (or the whole map/world) for cursed
-creatures (ghosts who were put to rest, killed vampires, ...) are ignored.
+creatures (ghosts, vampires, necromancers, werebeasts, zombies, etc.).
-Undead skeletons, corpses, bodyparts and the like are all thrown into the curse
+
-category "zombie". Anonymous zombies and resurrected body parts will show
+With an active in-game cursor, only the selected tile will be checked. Without a
-as "unnamed creature".
+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>]
 
 Options:
 
-:detail:      Print full name, date of birth, date of curse and some status
+- ``detail``
-              info (some vampires might use fake identities in-game, though).
+   Print full name, date of birth, date of curse, and some status info (some
-:ids:         Print the creature and race IDs.
+   vampires might use fake identities in-game, though).
-:nick:        Set the type of curse as nickname (does not always show up
+- ``nick``
-              in-game, some vamps don't like nicknames).
+   Set the type of curse as nickname (does not always show up in-game; some
-:all:         Include dead and passive cursed creatures (can result in a quite
+   vamps don't like nicknames).
-              long list after having FUN with necromancers).
+- ``ids``
-:verbose:     Print all curse tags (if you really want to know it all).
+   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``
+- ``cursecheck``
-   Give detailed info about all cursed creatures including deceased ones (no
+   Display a count of cursed creatures on the map (or under the cursor).
-   in-game cursor).
+- ``cursecheck detail all``
-``cursecheck nick``
+   Give detailed info about all cursed creatures including deceased ones.
-   Give a nickname all living/active cursed creatures on the map(no in-game
+- ``cursecheck nick``
-   cursor).
+   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" -
+    If you see any living/active creatures with a cursetype of "unknown", then
-    this is most likely with mods which introduce new types of curses.
+    it is most likely a new type of curse introduced by a mod.

docs/plugins/spotclean.rst

@@ -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

plugins/changelayer.cpp

@@ -37,7 +37,7 @@ DFhackCExport command_result plugin_init ( color_ostream &out, std::vector <Plug
 {
     commands.push_back(PluginCommand(
         "changelayer",
-        "Change a whole geology layer.",
+        "Change the material of an entire geology layer.",
         changelayer));
     return CR_OK;
 }

plugins/changevein.cpp

@@ -85,7 +85,7 @@ command_result df_changevein (color_ostream &out, vector <string> & parameters)
 DFhackCExport command_result plugin_init ( color_ostream &out, std::vector <PluginCommand> &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;
 }

plugins/cleaners.cpp

@@ -242,11 +242,11 @@ DFhackCExport command_result plugin_init ( color_ostream &out, std::vector <Plug
 {
     commands.push_back(PluginCommand(
         "clean",
-        "Remove contaminants from tiles, items and creatures.",
+        "Remove contaminants from tiles, items, and creatures.",
         clean));
     commands.push_back(PluginCommand(
         "spotclean",
-        "Cleans map tile under cursor.",
+        "Clean the map tile under the cursor.",
         spotclean,Gui::cursor_hotkey));
     return CR_OK;
 }

plugins/command-prompt.cpp

@@ -344,11 +344,10 @@ bool hotkey_allow_all(df::viewscreen *top)
 DFhackCExport command_result plugin_init(color_ostream &out, std::vector <PluginCommand> &commands)
 {
     commands.push_back(PluginCommand(
-                "command-prompt", "Shows a command prompt on window.",
+                "command-prompt",
-                show_prompt, hotkey_allow_all,
+                "An in-game DFHack terminal.",
-                "command-prompt [entry] - shows a cmd prompt in df window."
+                show_prompt,
-                " Entry is used for default prefix (e.g. ':lua')"
+                hotkey_allow_all));
-        ));
     return CR_OK;
 }
 

plugins/confirm.cpp

@@ -547,13 +547,8 @@ DFhackCExport command_result plugin_init (color_ostream &out, vector <PluginComm
         return CR_FAILURE;
     commands.push_back(PluginCommand(
         "confirm",
-        "Confirmation dialogs",
+        "Add confirmation dialogs for destructive actions.",
-        df_confirm,
+        df_confirm));
-        false, //allow non-interactive use
-
-        "  confirm enable|disable option|all ...\n"
-        "  confirm help|status\n"
-    ));
     return CR_OK;
 }
 

plugins/createitem.cpp

@@ -48,27 +48,10 @@ command_result df_createitem (color_ostream &out, vector <string> & parameters);
 
 DFhackCExport command_result plugin_init (color_ostream &out, std::vector<PluginCommand> &commands)
 {
-    commands.push_back(PluginCommand("createitem", "Create arbitrary items.", df_createitem, false,
+    commands.push_back(
-        "Syntax: createitem <item> <material> [count]\n"
+        PluginCommand("createitem",
-        "    <item> - Item token for what you wish to create, as specified in custom\n"
+                      "Create arbitrary items.",
-        "             reactions. If the item has no subtype, omit the :NONE.\n"
+                      df_createitem));
-        "    <material> - 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 <destination>'.\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"
-    ));
     return CR_OK;
 }
 

plugins/cromulate.cpp

@@ -13,9 +13,7 @@ command_result cromulate (color_ostream &out, std::vector <std::string> & parame
 DFhackCExport command_result plugin_init (color_ostream &out, std::vector <PluginCommand> &commands) {
     commands.push_back(PluginCommand("cromulate",
                                      "in-cpp plugin short desc", //to use one line in the ``[DFHack]# ls`` output
-                                     cromulate,
+                                     cromulate));
-                                     false,
-                                     "in-cpp plugin long help"));
     return CR_OK;
 }
 

plugins/cursecheck.cpp

@@ -79,9 +79,10 @@ 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",
+    commands.push_back(PluginCommand(
+        "cursecheck",
         "Check for cursed creatures (undead, necromancers...)",
-        cursecheck, false ));
+        cursecheck));
     return CR_OK;
 }