From e9e477c680948ea016e8c4dffe61c10ae6168ffe Mon Sep 17 00:00:00 2001
From: myk002 <myk002@yahoo.com>
Date: Wed, 20 Jul 2022 13:51:03 -0700
Subject: [PATCH] update docs for clean and spotclean

---
 docs/plugins/clean.rst     | 41 ++++++++++++++++++++++++++++----------
 docs/plugins/spotclean.rst | 14 ++++++++++---
 plugins/cleaners.cpp       | 26 ++++++------------------
 3 files changed, 48 insertions(+), 33 deletions(-)

diff --git a/docs/plugins/clean.rst b/docs/plugins/clean.rst
index f2d0c361d..54421ce91 100644
--- a/docs/plugins/clean.rst
+++ b/docs/plugins/clean.rst
@@ -1,16 +1,37 @@
 clean
 =====
-Cleans all the splatter that get scattered all over the map, items and
-creatures. In an old fortress, this can significantly reduce FPS lag. It can
-also spoil your !!FUN!!, so think before you use it.
 
-Options:
+Tags:
+:dfhack-keybind:
 
-:map:          Clean the map tiles. By default, it leaves mud and snow alone.
-:units:        Clean the creatures. Will also clean hostiles.
-:items:        Clean all the items. Even a poisoned blade.
+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.
 
-Extra options for ``map``:
+Usage::
 
-:mud:          Remove mud in addition to the normal stuff.
-:snow:         Also remove snow coverings.
+    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.
diff --git a/docs/plugins/spotclean.rst b/docs/plugins/spotclean.rst
index 9ccdd2cc6..dcad047a4 100644
--- a/docs/plugins/spotclean.rst
+++ b/docs/plugins/spotclean.rst
@@ -1,6 +1,14 @@
 spotclean
 =========
-Works like ``clean map snow mud``, but only for the tile under the cursor. Ideal
-if you want to keep that bloody entrance ``clean map`` would clean up.
 
-:dfhack-keybind:`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/cleaners.cpp b/plugins/cleaners.cpp
index 24694c6a2..7389488f1 100644
--- a/plugins/cleaners.cpp
+++ b/plugins/cleaners.cpp
@@ -241,27 +241,13 @@ 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","Remove contaminants from tiles, items and creatures.",
-        clean, false,
-        "  Removes contaminants from map tiles, items and creatures.\n"
-        "Options:\n"
-        "  map        - clean the map tiles\n"
-        "  items      - clean all items\n"
-        "  units      - clean all creatures\n"
-        "  plants     - clean all plants\n"
-        "  all        - clean everything.\n"
-        "More options for 'map':\n"
-        "  snow       - also remove snow\n"
-        "  mud        - also remove mud\n"
-        "  item       - also remove item spatters (e.g. leaves and flowers)\n"
-        "Example:\n"
-        "  clean all mud snow item\n"
-        "    Removes all spatter, including mud and snow from map tiles.\n"
-    ));
+        "clean",
+        "Remove contaminants from tiles, items and creatures.",
+        clean));
     commands.push_back(PluginCommand(
-        "spotclean","Cleans map tile under cursor.",
-        spotclean,Gui::cursor_hotkey
-    ));
+        "spotclean",
+        "Cleans map tile under cursor.",
+        spotclean,Gui::cursor_hotkey));
     return CR_OK;
 }