From ddae1aa90050a2917f6af008ad19470d324461cc Mon Sep 17 00:00:00 2001
From: myk002 <myk.taylor@gmail.com>
Date: Wed, 27 Jul 2022 17:14:40 -0700
Subject: [PATCH] update docs for liquids

---
 docs/plugins/liquids.rst | 51 ++++++++++++++++++++++------------------
 plugins/liquids.cpp      | 18 +++++++-------
 2 files changed, 36 insertions(+), 33 deletions(-)

diff --git a/docs/plugins/liquids.rst b/docs/plugins/liquids.rst
index 75e41da5b..61e4bcfe2 100644
--- a/docs/plugins/liquids.rst
+++ b/docs/plugins/liquids.rst
@@ -2,30 +2,42 @@
 
 liquids
 =======
-Allows adding magma, water and obsidian to the game. It replaces the normal
-dfhack command line and can't be used from a hotkey. Settings will be remembered
-as long as dfhack runs. Intended for use in combination with the command
-``liquids-here`` (which can be bound to a hotkey).  See also :issue:`80`.
+Tags:
+:dfhack-keybind:`liquids`
+:dfhack-keybind:`liquids-here`
 
-.. warning::
+Place magma, water or obsidian.  See `gui/liquids` for an in-game interface for
+this functionality.
+
+Also, if you only want to add or remove water or magma from a single tile, the
+`source` script may be easier to use.
+
+Usage:
 
-    Spawning and deleting liquids can mess up pathing data and
-    temperatures (creating heat traps). You've been warned.
+``liquids``
+    Start the interactive terminal settings interpreter. This command must be
+    called from the DFHack terminal and not from any in-game interface.
+``liquids-here``
+    Run the liquid spawner with the current/last settings made in ``liquids``
+    (if no settings in ``liquids`` were made, then it paints a point of 7/7
+    magma by default). This command is intended to be used as keybinding, and it
+    requires an active in-game cursor.
 
-.. note::
+.. warning::
 
-    `gui/liquids` is an in-game UI for this script.
+    Spawning and deleting liquids can mess up pathing data and temperatures
+    (creating heat traps). You've been warned.
 
-Settings will be remembered until you quit DF. You can call `liquids-here` to execute
-the last configured action, which is useful in combination with keybindings.
+Interactive interpreter
+-----------------------
 
-Usage: point the DF cursor at a tile you want to modify and use the commands.
+The interpreter replaces the normal dfhack command line and can't be used from a
+hotkey. Settings will be remembered as long as dfhack runs. It is intended for
+use in combination with the command ``liquids-here`` (which *can* be bound to a
+hotkey).
 
-If you only want to add or remove water or magma from one tile,
-`source` may be easier to use.
+You can enter the following commands at the prompt.
 
-Commands
---------
 Misc commands:
 
 :q:                 quit
@@ -65,10 +77,3 @@ Brush size and shape:
 :block:         DF map block with cursor in it (regular spaced 16x16x1 blocks)
 :column:        Column from cursor, up through free space
 :flood:         Flood-fill water tiles from cursor (only makes sense with wclean)
-
-liquids-here
-------------
-Run the liquid spawner with the current/last settings made in liquids (if no
-settings in liquids were made it paints a point of 7/7 magma by default).
-
-Intended to be used as keybinding. Requires an active in-game cursor.
diff --git a/plugins/liquids.cpp b/plugins/liquids.cpp
index 76c098c8a..980deb747 100644
--- a/plugins/liquids.cpp
+++ b/plugins/liquids.cpp
@@ -65,17 +65,15 @@ DFhackCExport command_result plugin_init ( color_ostream &out, std::vector <Plug
 {
     liquids_hist.load(HISTORY_FILE);
     commands.push_back(PluginCommand(
-        "liquids", "Place magma, water or obsidian.",
-        df_liquids, true,
-        "This tool allows placing magma, water and other similar things.\n"
-        "It is interactive and further help is available when you run it.\n"
-        "The settings will be remembered until dfhack is closed and you can call\n"
-        "'liquids-here' (mapped to a hotkey) to paint liquids at the cursor position\n"
-        "without the need to go back to the dfhack console.\n")); // interactive, needs console for prompt
+        "liquids",
+        "Place magma, water or obsidian.",
+        df_liquids,
+        true)); // interactive, needs console for prompt
     commands.push_back(PluginCommand(
-        "liquids-here", "Use settings from liquids at cursor position.",
-        df_liquids_here, Gui::cursor_hotkey, // non-interactive, needs ingame cursor
-        "  This command is intended to be mapped to a hotkey and is identical to pressing Enter in liquids with the current parameters.\n"));
+        "liquids-here",
+        "Use settings from liquids at cursor position.",
+        df_liquids_here,
+        Gui::cursor_hotkey)); // non-interactive, needs ingame cursor
     return CR_OK;
 }