write autochop docs and proposed API

docs/plugins/autochop.rst

@@ -4,9 +4,19 @@ autochop
 .. dfhack-tool::
     :summary: Auto-harvest trees when low on stockpiled logs.
     :tags: fort auto plants
-    :no-command:
 
-This plugin can designate trees for chopping when your stocks are low on logs.
+This plugin can automatically designate trees for chopping when your stocks are
+low on logs. It can also ensure specified burrows are kept clear of trees, so,
+for example, caravans always have a path to your depot and trees won't grow
+close to your walls, giving invaders an unexpected path into your fort.
+
+Autochop checks your stock of logs and designates appropriate trees for chopping
+once every in-game day. Logs that are forbidden or inaccessible (e.g. in hidden
+parts of the map, under water, etc.) are not counted towards your target. Trees
+that are inaccessible are likewise never designated. Tree cutting quota
+agreements that you have made are respected (by default).
+
+Please see `gui/autochop` for the interactive configuration dialog.
 
 Usage
 -----
@@ -14,14 +24,57 @@ Usage
 ::
 
     enable autochop
+    autochop [status]
+    autochop (designate|undesignate)
+    autochop target <max> [<min>]
+    autochop quota (abide|ignore)
+    autochop restrict (set|add|remove) <burrow>[,<burrow>...]
+    autochop clearcut (set|add|remove) <burrow>[,<burrow>...]
+    autochop (protect|unprotect) <type>[,<type>...]
+
+Examples
+--------
+
+Ensure we always have about 500 logs in stock, harvested from anywhere on the
+map. Also ensure the caravan pathway and the area around the outer wall is
+always clear (requires existence of appropriately-named burrows)::
+
+    autochop target 500
+    autochop clearcut CaravanPath,OuterWall
+    enable autochop
+
+Commands
+--------
+
+``status``
+    Show current configuration and statistics, including tree cutting quota
+    agreement status.
+
+``designate``
+    Designate trees for chopping right now according to the current
+    configuration. This works even if ``autochop`` is not currently enabled.
+
+``undesignate``
+    Undesignates all trees.
+
+``target <max> [<min>]``
+    Set the target range for the number of logs you want to have in stock. If a
+    minimum amount is not specified, it defaults to 20% less than the maximum.
+    The default target is ``200`` (with a corresponding minimum of ``160``).
 
-Then, open the settings menu with :kbd:`c` from the designations menu (the
+``quota (abide|ignore)``
-option appears when you have "Chop Down Trees" selected with :kbd:`d`-:kbd:`t`).
+    Choose whether to abide by or ignore tree cutting quota agreements that you
+    may have signed with friendly elven civilizations. By default, ``autochop``
+    will abide by any agreements you have made.
 
-Set your desired thresholds and enable autochopping with :kbd:`a`.
+``restrict (set|add|remove) <burrow>[,<burrow>...]``
+    Instead of choosing trees across the whole game map, restrict tree cutting
+    to the given burrows. Burrows can be specified by name or internal ID.
 
-You can also restrict autochopping to specific burrows. Highlight a burrow name
+``clearcut (set|add|remove) <burrow>[,<burrow>...]``
-with the Up/Down arrow keys and hit :kbd:`Enter` to mark it as the autochop
+    Ensure the given burrows are always clear of trees. As soon as a tree
-burrrow.
+    appears in any of these burrows, it is designated for chopping.
 
-Autochop checks your stock of logs and designates trees once every in game day.
+``protect <type>[,<type>...]``, ``unprotect <type>[,<type>...]``
+    Choose whether to exclude trees from chopping that produce any of the given
+    types of food. Valid types are: ``brewable``, ``edible``, and ``cookable``.