From 08d434d16ea24d902c0f0b9fe8da5ac9e09d5972 Mon Sep 17 00:00:00 2001
From: myk002 <myk002@yahoo.com>
Date: Sun, 31 Jul 2022 13:29:40 -0700
Subject: [PATCH] update docs for stockflow

---
 docs/plugins/stockflow.rst | 39 +++++++++++++++++++-------------------
 plugins/stockflow.cpp      | 32 +++++--------------------------
 2 files changed, 25 insertions(+), 46 deletions(-)

diff --git a/docs/plugins/stockflow.rst b/docs/plugins/stockflow.rst
index c3db7a673..0e2f5a1ad 100644
--- a/docs/plugins/stockflow.rst
+++ b/docs/plugins/stockflow.rst
@@ -1,24 +1,14 @@
 stockflow
 =========
-Allows the fortress bookkeeper to queue jobs through the manager,
-based on space or items available in stockpiles.
+Tags:
+:dfhack-keybind:`stockflow`
 
-Inspired by `workflow`.
+Queue manager jobs based on free space in stockpiles. With this plugin, the
+fortress bookkeeper can tally up free space in specific stockpiles and queue
+jobs through the manager to produce items to fill the free space.
 
-Usage:
-
-``stockflow enable``
-    Enable the plugin.
-``stockflow disable``
-    Disable the plugin.
-``stockflow fast``
-    Enable the plugin in fast mode.
-``stockflow list``
-    List any work order settings for your stockpiles.
-``stockflow status``
-    Display whether the plugin is enabled.
-
-While enabled, the :kbd:`q` menu of each stockpile will have two new options:
+When the plugin is enabled, the :kbd:`q` menu of each stockpile will have two
+new options:
 
 * :kbd:`j`:  Select a job to order, from an interface like the manager's screen.
 * :kbd:`J`:  Cycle between several options for how many such jobs to order.
@@ -27,5 +17,16 @@ Whenever the bookkeeper updates stockpile records, new work orders will
 be placed on the manager's queue for each such selection, reduced by the
 number of identical orders already in the queue.
 
-In fast mode, new work orders will be enqueued once per day, instead of
-waiting for the bookkeeper.
+This plugin is similar to `workflow`, but uses stockpiles to manage job triggers
+instead of abstract stock quantities.
+
+Usage:
+
+``enable stockflow``
+    Enable the plugin.
+``stockflow status``
+    Display whether the plugin is enabled.
+``stockflow list``
+    List any work order settings for your stockpiles.
+``stockflow fast``
+    Enqueue orders once per day instead of waiting for the bookkeeper.
diff --git a/plugins/stockflow.cpp b/plugins/stockflow.cpp
index aede089ad..65223f603 100644
--- a/plugins/stockflow.cpp
+++ b/plugins/stockflow.cpp
@@ -29,30 +29,6 @@ REQUIRE_GLOBAL(world);
 REQUIRE_GLOBAL(ui);
 
 bool fast = false;
-const char *tagline = "Allow the bookkeeper to queue manager jobs.";
-const char *usage = (
-    "  stockflow enable\n"
-    "    Enable the plugin.\n"
-    "  stockflow disable\n"
-    "    Disable the plugin.\n"
-    "  stockflow fast\n"
-    "    Enable the plugin in fast mode.\n"
-    "  stockflow list\n"
-    "    List any work order settings for your stockpiles.\n"
-    "  stockflow status\n"
-    "    Display whether the plugin is enabled.\n"
-    "\n"
-    "While enabled, the 'q' menu of each stockpile will have two new options:\n"
-    "  j: Select a job to order, from an interface like the manager's screen.\n"
-    "  J: Cycle between several options for how many such jobs to order.\n"
-    "\n"
-    "Whenever the bookkeeper updates stockpile records, new work orders will\n"
-    "be placed on the manager's queue for each such selection, reduced by the\n"
-    "number of identical orders already in the queue.\n"
-    "\n"
-    "In fast mode, new work orders will be enqueued once per day, instead of\n"
-    "waiting for the bookkeeper.\n"
-);
 
 /*
  * Lua interface.
@@ -342,8 +318,7 @@ static command_result stockflow_cmd(color_ostream &out, vector <string> & parame
             desired = true;
             fast = true;
         } else if (parameters[0] == "usage" || parameters[0] == "help" || parameters[0] == "?") {
-            out.print("%s: %s\nUsage:\n%s", plugin_name, tagline, usage);
-            return CR_OK;
+            return CR_WRONG_USAGE;
         } else if (parameters[0] == "list") {
             if (!enabled) {
                 out.printerr("Stockflow is not currently enabled.\n");
@@ -416,7 +391,10 @@ DFhackCExport command_result plugin_init(color_ostream &out, std::vector <Plugin
         enabled = true;
     }
 
-    commands.push_back(PluginCommand(plugin_name, tagline, stockflow_cmd, false, usage));
+    commands.push_back(PluginCommand(
+        plugin_name,
+        "Queue manager jobs based on free space in stockpiles.",
+        stockflow_cmd));
     return CR_OK;
 }