define new docs/behavior for combine

docs/combine.rst

@@ -5,6 +5,21 @@ combine
     :summary: Combine items that can be stacked together.
     :tags: fort productivity items plants stockpiles
 
+This handy tool "defragments" your items without giving your fort an undue
+advantage of unreasonably large stacks. Within stockpiles and built containers,
+similar items will be combined into fewer, larger stacks for more compact and
+easier-to-manage storage. Cloth and thread that has been partially used by
+hospitals will be rebalanced so that the used parts are associated with the
+fewest number of cloth/thread items possible. Finally, partial bars that
+accumulate in smelters when you melt metal items are gathered together so
+complete, usable bars can be created.
+
+Items inside of stockpiles or built containers will not be combined with items
+outside of those stockpiles or containers. Cloth and thread, however, can be
+dropped anywhere after being partially used, so cloth and thread is combined
+across the entire fort. If a full bar is collected from your smelters, it will
+appear at one of the smelters that contributed to that metal type.
+
 Usage
 -----
 
@@ -14,77 +29,77 @@ Usage
 
 Examples
 --------
-``combine``
-    Displays help
 ``combine all --dry-run``
-    Preview stack changes for all types in all stockpiles.
+    Preview what will be combined for all types in all
+    stockpiles/containers/smelters.
 ``combine all``
-    Merge stacks for all stockpile and all types
+    Merge all items in all stockpiles/containers/smelters.
 ``combine all --types=meat,plant``
-    Merge ``meat`` and ``plant`` type stacks in all stockpiles.
+    Merge ``meat`` and ``plant`` type stacks in all stockpiles and containers.
 ``combine here``
-    Merge stacks in the selected stockpile.
+    Merge stacks in the currently selected stockpile or container, or collect
+    all accumulated metal bars to the currently selected smelter.
 
 Commands
 --------
 ``all``
-    Search all stockpiles.
+    Combine things in all stockpiles, built containers, and smelters.
 ``here``
-    Search the currently selected stockpile.
+    Combine items in the currently selected stockpile or container, or collect
+    partial bars from all smelters into the selected smelter.
 
 Options
 -------
-``-h``, ``--help``
-    Prints help text. Default if no options are specified.
-
 ``-d``, ``--dry-run``
-    Display the stack changes without applying them.
-
+    Display what would be combined instead of actually combining items.
 ``-t``, ``--types <comma separated list of types>``
-    Filter item types. Default is ``all``. Valid types are:
-
-        ``all``:   all of the types listed here.
-
-        ``ammo``: AMMO
-
-        ``drink``: DRINK
-
-        ``fat``:   GLOB and CHEESE
-
-        ``fish``:  FISH, FISH_RAW and EGG
-
-        ``food``:  FOOD
+    Specify which item types should be combined. Default is ``all``. Valid
+    types are:
+    :all: all of the types listed here
+    :ammo: stacks of ammunition
+    :bars: partial bars left over in smelters
+    :cloth: cloth
+    :drink: stacks of drinks in barrels/pots
+    :fat: cheese, fat, tallow, and other globs
+    :fish: raw and prepared fish. this category also includes all types of eggs
+    :food: prepared food
+    :meat: meat
+    :parts: corpse pieces
+    :plant: plants and plant growths
+    :powders: dye and other non-sand, non-plaster powders
+    :seed: seeds
+    :thread: thread
+``-q``, ``--quiet``
+    Don't print the final item distribution summary.
+``-v``, ``--verbose n``
+    Print verbose output for debugging purposes, n from 1 to 4.
 
-        ``meat``:  MEAT
+Notes
+-----
 
-        ``parts``: CORPSEPIECE
+The following conditions prevent an item from being combined:
 
-        ``plant``: PLANT and PLANT_GROWTH
+1. An item is not in a stockpile.
+2. An item is sand or plaster.
+3. An item is rotten, forbidden/hidden, marked for dumping/melting, on
+    fire, encased, owned by a trader/hostile/dwarf or is in a spider web.
+4. An item is part of a corpse and has not been butchered.
 
-        ``powders``: POWDERS_MISC
+Moreover, if a stack is in a container associated with a stockpile, the stack
+will not be able to grow past the volume limit of the container.
 
-        ``seed``: SEEDS
+An item can be combined with others if it:
 
-``-q``, ``--quiet``
-    Only print changes instead of a summary of all processed stockpiles.
+1. has an associated race/caste and is of the same item type, race, and caste
+2. has the same type, material, and quality. If it is a masterwork, it is also
+   grouped by who created it.
 
-``-v``, ``--verbose n``
-    Print verbose output, n from 1 to 4.
+Since the player cannot easily choose what kind of cloth and thread the
+hospital uses to dress and suture wounds, `combine` will refill more expensive
+cloth/thread first and deduct accordingly from cheaper cloth/thread. Existing
+wound dressings and sutures that used the more expensive materials will be
+modified to use the cheaper materials.
 
-Notes
------
-The following conditions prevent an item from being combined:
-    1. An item is not in a stockpile.
-    2. An item is sand or plaster.
-    3. An item is rotten, forbidden/hidden, marked for dumping/melting, on fire, encased, owned by a trader/hostile/dwarf or is in a spider web.
-    4. An item is part of a corpse and not butchered.
-
-The following categories are defined:
-    1. Corpse pieces, grouped by piece type and race
-    2. Items that have an associated race/caste, grouped by item type,  race, and caste
-    3. Ammo, grouped by ammo type, material, and quality. If the ammo is a masterwork, it is also grouped by who created it.
-    4. Anything else, grouped by item type and material
-
-Each category has a default stack size of 30 unless a larger stack already
-exists "naturally" in your fort. In that case the largest existing stack size
-is used.
+When partial bars are collected in smelters, collected whole bars are spawned
+at one of the smelters that had a partial amount of that bar. Any remaining
+partial amounts of spawned bar materials will be associated with that smelter.