From b93e3365f6d8fb1281d8de49c680a38d1fe084be Mon Sep 17 00:00:00 2001
From: myk002 <myk002@yahoo.com>
Date: Mon, 25 Jul 2022 21:50:52 -0700
Subject: [PATCH] update docs for get plants

---
 docs/plugins/getplants.rst | 69 ++++++++++++++++++++++++--------------
 plugins/getplants.cpp      | 21 ++----------
 2 files changed, 46 insertions(+), 44 deletions(-)

diff --git a/docs/plugins/getplants.rst b/docs/plugins/getplants.rst
index 5a719b3ab..167ac72f2 100644
--- a/docs/plugins/getplants.rst
+++ b/docs/plugins/getplants.rst
@@ -1,24 +1,48 @@
 getplants
 =========
-This tool allows plant gathering and tree cutting by RAW ID. Specify the types
-of trees to cut down and/or shrubs to gather by their plant names, separated
-by spaces.
-
-Options:
-
-:``-t``: Tree: Select trees only (exclude shrubs)
-:``-s``: Shrub: Select shrubs only (exclude trees)
-:``-f``: Farming: Designate only shrubs that yield seeds for farming. Implies -s
-:``-c``: Clear: Clear designations instead of setting them
-:``-x``: eXcept: Apply selected action to all plants except those specified (invert
-     selection)
-:``-a``: All: Select every type of plant (obeys ``-t``/``-s``/``-f``)
-:``-v``: Verbose: Lists the number of (un)designations per plant
-:``-n *``: Number: Designate up to * (an integer number) plants of each species
-
-Specifying both ``-t`` and ``-s`` or ``-f`` will have no effect. If no plant IDs are
-specified, all valid plant IDs will be listed, with ``-t``, ``-s``, and ``-f``
-restricting the list to trees, shrubs, and farmable shrubs, respectively.
+Tags:
+:dfhack-keybind:`getplants`
+
+Designate trees for chopping and shrubs for gathering. Specify the types of
+trees to cut down and/or shrubs to gather by their plant names.
+
+Usage:
+
+``getplants [-t|-s|-f]``
+    List valid tree/shrub ids, optionally restricted to the specified type.
+``getplants <id> [<id> ...] [<options>]``
+    Designate trees/shrubs of the specified types for chopping/gathering.
+
+Examples
+--------
+
+``getplants``
+    List all valid IDs.
+``getplants -f -a``
+    Gather all plants on the map that yield seeds for farming.
+``getplants NETHER_CAP -n 10``
+    Designate 10 nether cap trees for chopping.
+
+Options
+-------
+
+``-t``
+    Tree: Select trees only (exclude shrubs).
+``-s``
+    Shrub: Select shrubs only (exclude trees).
+``-f``
+    Farming: Designate only shrubs that yield seeds for farming.
+``-a``
+    All: Select every type of plant (obeys ``-t``/``-s``/``-f``).
+``-c``
+    Clear: Clear designations instead of setting them.
+``-x``
+    eXcept: Apply selected action to all plants except those specified (invert
+    selection).
+``-v``
+    Verbose: Lists the number of (un)designations per plant.
+``-n <num>``
+    Number: Designate up to the specified number of plants of each species.
 
 .. note::
 
@@ -28,10 +52,3 @@ restricting the list to trees, shrubs, and farmable shrubs, respectively.
     This leads to some shrubs being designated when they shouldn't be, causing a
     plant gatherer to walk there and do nothing (except clearing the
     designation). See :issue:`1479` for details.
-
-    The implementation another known deficiency: it's incapable of detecting that
-    raw definitions that specify a seed extraction reaction for the structural part
-    but has no other use for it cannot actually yield any seeds, as the part is
-    never used (parts of :bug:`6940`, e.g. Red Spinach), even though DF
-    collects it, unless there's a workshop reaction to do it (which there isn't
-    in vanilla).
diff --git a/plugins/getplants.cpp b/plugins/getplants.cpp
index 25823eb17..6819b6191 100644
--- a/plugins/getplants.cpp
+++ b/plugins/getplants.cpp
@@ -584,24 +584,9 @@ command_result df_getplants (color_ostream &out, vector <string> & parameters)
 DFhackCExport command_result plugin_init ( color_ostream &out, vector <PluginCommand> &commands)
 {
     commands.push_back(PluginCommand(
-        "getplants", "Cut down trees or gather shrubs by ID",
-        df_getplants, false,
-        "  Specify the types of trees to cut down and/or shrubs to gather by their\n"
-        "  plant IDs, separated by spaces.\n"
-        "Options:\n"
-        "  -t - Tree: Select trees only (exclude shrubs)\n"
-        "  -s - Shrub: Select shrubs only (exclude trees)\n"
-        "  -f - Farming: Designate only shrubs that yield seeds for farming. Implies -s\n"
-        "  -c - Clear: Clear designations instead of setting them\n"
-        "  -x - eXcept: Apply selected action to all plants except those specified\n"
-        "  -a - All: Select every type of plant (obeys -t/-s/-f)\n"
-        "  -v - Verbose: List the number of (un)designations per plant\n"
-        "  -n * - Number: Designate up to * (an integer number) plants of each species\n"
-        "Specifying both -t and -s or -f will have no effect.\n"
-        "If no plant IDs are specified, and the -a switch isn't given, all valid plant\n"
-        "IDs will be listed with -t, -s, and -f restricting the list to trees, shrubs,\n"
-        "and farmable shrubs, respectively.\n"
-    ));
+        "getplants",
+        "Designate trees for chopping and shrubs for gathering.",
+        df_getplants));
     return CR_OK;
 }