Merge pull request #1500 from amade-w/store-owned

add new tool `store-owned`

Author: ab9rf

changelog.txt

@@ -29,6 +29,7 @@ Template for new versions:
 ## New Tools
 - `fix/archery-practice`: combine ammo items in units' quivers to fix 'Soldier (no item)' issue
 - `gui/adv-finder`: UI for tracking historical figures and artifacts in adventure mode
+- `store-owned`: task owned items to be stored in the owner's room furniture
 
 ## New Features
 
@@ -49,7 +50,6 @@ Template for new versions:
 - `autotraining`: new tool to assign citizens to a military squad when they need Martial Training
 - `gui/autotraining`: configuration tool for autotraining
 - `entomb`: allow any unit that has a corpse or body parts to be assigned a tomb zone
-
 - `husbandry`: Automatically milk and shear animals at nearby farmer's workshops
 
 ## New Features

docs/store-owned.rst

@@ -0,0 +1,43 @@
+store-owned
+===========
+
+.. dfhack-tool::
+    :summary: Task units to store their owned items.
+    :tags: fort items buildings
+
+Task any owned item to be stored in an appropriate storage furniture in
+a room assigned to the item's owner.
+
+Usage
+-----
+
+``store-owned [<option>]``
+
+Select an owned item and run the tool to task the owner to put the item
+into storage.
+
+If the storage furniture is full, unreachable, or unavailable, the item
+will be dropped off on the floor of the owner's room. If the owner has
+no assigned room or is unable to access their room(s), the item will be
+stored in the dormitory if available. If the dormitory is unreachable or
+unavailable, the item will be dropped off at the trade depot instead.
+
+This tool can be used to unburden a unit that has acquired too many
+trinkets, or simply as an alternative to ``cleanowned`` when cleaning
+up scattered owned items. It can also be used to force a unit to
+relinquish ownership of the selected item.
+
+Options
+-------
+
+``--dorm``
+    Task the selected owned item for storage in an appropriate storage
+    furniture, or on the floor, in any available dormitory zone.
+
+``--depot``
+    Task the selected owned item to be dropped off at the trade depot.
+
+``--discard``
+    Force the owner of the selected item to relinquish ownership of
+    said item. The item will not be tasked for storage. If the item
+    is in the owner's inventory, they will drop it on the ground.