update docs for gui "w" scripts

myk002 · myk002 · commit ca280f26b358 · 2022-09-08T22:26:25.000-07:00
diff --git a/docs/gui/workflow.rst b/docs/gui/workflow.rst
@@ -1,61 +1,57 @@
-
 gui/workflow
 ============
 
 .. dfhack-tool::
-    :summary: todo.
+    :summary: Manage automated item production rules.
     :tags: fort auto jobs
 
-
-Bind to a key (the example config uses Alt-W), and activate with a job selected
-in a workshop in :kbd:`q` mode.
+This tool provides a simple interface to item production constraints managed by
+`workflow`. When a workshop job is selected in :kbd:`q` mode and this tool is
+invoked, it displays the constraints applicable to the current job and their
+current status. It also allows you to modify existing constraints or add new
+ones.
 
 .. image:: /docs/images/workflow.png
 
-This script provides a simple interface to constraints managed by `workflow`.
-When active, it displays a list of all constraints applicable to the
-current job, and their current status.
-
-A constraint specifies a certain range to be compared against either individual
-*item* or whole *stack* count, an item type and optionally a material. When the
-current count is below the lower bound of the range, the job is resumed; if it
-is above or equal to the top bound, it will be suspended. Within the range, the
-specific constraint has no effect on the job; others may still affect it.
-
-Pressing :kbd:`i` switches the current constraint between counting stacks or items.
-Pressing :kbd:`r` lets you input the range directly;
-:kbd:`e`, :kbd:`r`, :kbd:`d`, :kbd:`f` adjust the
-bounds by 5, 10, or 20 depending on the direction and the :kbd:`i` setting (counting
-items and expanding the range each gives a 2x bonus).
-
-Pressing :kbd:`a` produces a list of possible outputs of this job as guessed by
-workflow, and lets you create a new constraint by choosing one as template. If you
-don't see the choice you want in the list, it likely means you have to adjust
-the job material first using `job` ``item-material`` or `gui/workshop-job`,
-as described in the `workflow` documentation. In this manner, this feature
-can be used for troubleshooting jobs that don't match the right constraints.
+A constraint is a target range to be compared against either the number of
+individual itemis or the number of item stacks. It also includes an item type
+and, optionally, a material. When the current stock count is below the lower
+bound of the range, the job is resumed; if it is above or equal to the top
+bound, it will be suspended. If there are multiple constraints, being out of the
+range of any constraint will cause the job to be suspended.
+
+Pressing :kbd:`I` switches the current constraint between counting stacks and
+counting individual items. Pressing :kbd:`R` lets you input the range directly,
+or :kbd:`e`, :kbd:`r`, :kbd:`d`, :kbd:`f` incrementally adjusts the bounds.
+
+Pressing :kbd:`A` produces a list of possible outputs of this job as guessed by
+workflow, and lets you create a new constraint by choosing one as template. If
+you don't see the choice you want in the list, it likely means you have to
+adjust the job material first using `job item-material <job>` or
+`gui/workshop-job`, as described in the `workflow` documentation. In this
+manner, this feature can be used for troubleshooting jobs that don't match the
+right constraints.
 
 .. image:: /docs/images/workflow-new1.png
 
-If you select one of the outputs with :kbd:`Enter`, the matching constraint is simply
-added to the list. If you use :kbd:`Shift`:kbd:`Enter`, the interface proceeds to the
-next dialog, which allows you to edit the suggested constraint parameters to
-suit your need, and set the item count range.
+If you select one of the outputs with :kbd:`Enter`, the matching constraint is
+simply added to the list. If you use :kbd:`Shift`:kbd:`Enter`, the interface
+proceeds to the next dialog, which allows you to edit the suggested constraint
+parameters and set the item count range.
 
 .. image:: /docs/images/workflow-new2.png
 
-Pressing :kbd:`s` (or, with the example config, Alt-W in the :kbd:`z` stocks screen)
-opens the overall status screen:
+Pressing :kbd:`S` (or by using the hotkey in the :kbd:`z` stocks screen) opens
+the overall status screen where you can manage constraints for all jobs:
 
 .. image:: /docs/images/workflow-status.png
 
 This screen shows all currently existing workflow constraints, and allows
-monitoring and/or changing them from one screen. The constraint list can
-be filtered by typing text in the field below.
+monitoring and/or changing them from one screen.
 
-The color of the stock level number indicates how "healthy" the stock level
-is, based on current count and trend. Bright green is very good, green is good,
-red is bad, bright red is very bad.
+The color of the stock level number indicates how "healthy" the stock level is,
+based on current count and trend. Bright green is very good, green is good, red
+is bad, bright red is very bad.
 
 The limit number is also color-coded. Red means that there are currently no
 workshops producing that item (i.e. no jobs). If it's yellow, that means the
@@ -65,3 +61,11 @@ The chart on the right is a plot of the last 14 days (28 half day plots) worth
 of stock history for the selected item, with the rightmost point representing
 the current stock value. The bright green dashed line is the target
 limit (maximum) and the dark green line is that minus the gap (minimum).
+
+Usage
+-----
+
+``gui/workflow``
+    View and manage constraints for the currently selected workshop job.
+``gui/workflow status``
+    View and manage constraints across all `workflow` managed jobs.
diff --git a/docs/gui/workorder-details.rst b/docs/gui/workorder-details.rst
@@ -1,21 +1,20 @@
-
 gui/workorder-details
 =====================
 
 .. dfhack-tool::
-    :summary: todo.
+    :summary: Adjust input materials and traits for workorders.
     :tags: fort inspection workorders
 
+This tool allows you to adjust item types, materials, and/or traits for items
+used in manager workorders. The jobs created from those workorders will inherit
+the details.
 
-Adjust input items, material, or traits for work orders. Actual
-jobs created for it will inherit the details.
-
-This is the equivalent of `gui/workshop-job` for work orders,
-with the additional possibility to set input items' traits.
+Invoke while on a work order's detail screen (:kbd:`j-m`, select work order,
+:kbd:`d`).
 
-It has to be run from a work order's detail screen
-(:kbd:`j-m`, select work order, :kbd:`d`).
+Usage
+-----
 
-For best experience add the following to your ``dfhack*.init``::
+::
 
-    keybinding add D@workquota_details gui/workorder-details
+    gui/workorder-details
diff --git a/docs/gui/workshop-job.rst b/docs/gui/workshop-job.rst
@@ -1,51 +1,51 @@
-
 gui/workshop-job
 ================
 
 .. dfhack-tool::
-    :summary: todo.
+    :summary: Adjust the input materials used for a job at a workshop.
     :tags: fort inspection jobs
 
-
-Run with a job selected in a workshop in the :kbd:`q` mode.
+This tool allows you to inspect or change the input reagents for the selected
+workshop job (in :kbd:`q` mode).
 
 .. image:: /docs/images/workshop-job.png
 
-The script shows a list of the input reagents of the selected job, and allows changing
-them like the `job` ``item-type`` and `job` ``item-material`` commands.
-
-Specifically, pressing the :kbd:`i` key pops up a dialog that lets you select an item
-type from a list.
+Pressing :kbd:`i` shows a dialog where you can select an item type from a list.
 
 .. image:: /docs/images/workshop-job-item.png
 
-Pressing :kbd:`m`, unless the item type does not allow a material,
-lets you choose a material.
+Pressing :kbd:`m` (unless the item type does not allow a material) lets you
+choose a material.
 
 .. image:: /docs/images/workshop-job-material.png
 
-Since there are a lot more materials than item types, this dialog is more complex
-and uses a hierarchy of sub-menus. List choices that open a sub-menu are marked
-with an arrow on the left.
+Since there are a lot more materials than item types, this dialog is more
+complex and uses a hierarchy of sub-menus. List choices that open a sub-menu are
+marked with an arrow on the left.
 
 .. warning::
 
-  Due to the way input reagent matching works in DF, you must select an item type
-  if you select a material, or the material will be matched incorrectly in some cases.
-  If you press :kbd:`m` without choosing an item type, the script will auto-choose
-  if there is only one valid choice, or pop up an error message box instead of the
-  material selection dialog.
-
-Note that both materials and item types presented in the dialogs are filtered
-by the job input flags, and even the selected item type for material selection,
-or material for item type selection. Many jobs would let you select only one
-input item type.
-
-For example, if you choose a *plant* input item type for your prepare meal job,
-it will only let you select cookable materials.
-
-If you choose a *barrel* item instead (meaning things stored in barrels, like
-drink or milk), it will let you select any material, since in this case the
-material is matched against the barrel itself. Then, if you select, say, iron,
-and then try to change the input item type, now it won't let you select *plant*;
-you have to unset the material first.
+    Due to the way input reagent matching works in DF, you must select an item
+    type if you select a material or the material may be matched incorrectly. If
+    you press :kbd:`m` without choosing an item type, the script will
+    auto-choose if there is only one valid choice.
+
+Note that the choices presented in the dialogs are constrained by the job input
+flags. For example, if you choose a ``plant`` input item type for your ``prepare
+meal`` job, it will only let you select cookable plants since the job reagent
+has the ``cookable`` trait.
+
+As another example, if you choose a ``barrel`` item for your ``prepare meal``
+job (meaning things stored in barrels, like drink or milk), it will let you
+select any material that barrels can be made out of, since in this case the
+material is matched against the barrel itself. Then, if you select, say,
+``iron``, and then try to change the input item type, it won't let you select
+``plant`` because plants cannot be made of iron -- you have to unset the
+material first.
+
+Usage
+-----
+
+::
+
+    gui/workshop-job
