update docs

docs/guides/quickfort-user-guide.rst

@@ -1308,7 +1308,7 @@ legacy Python Quickfort. This setting has no effect on DFHack Quickfort, which
 will use buildingplan to manage everything designated in a ``#build`` blueprint
 regardless of the buildingplan UI settings.
 
-However, quickfort *does* use `buildingplan's filters <buildingplan-filters>`
+However, quickfort *does* use `buildingplan's filters <buildingplan>`
 for each building type. For example, you can use the buildingplan UI to set the
 type of stone you want your walls made out of. Or you can specify that all
 buildingplan-managed chairs and tables must be of Masterful quality. The current

docs/plugins/buildingplan.rst

@@ -2,32 +2,73 @@ buildingplan
 ============
 
 .. dfhack-tool::
-    :summary: Plan building construction before you have materials.
+    :summary: Plan building layouts with or without materials.
     :tags: fort design buildings
 
-This plugin adds a planning mode for building placement. You can then place
+Buildingplan allows you to place furniture, constructions, and other buildings,
-furniture, constructions, and other buildings before the required materials are
+regardless of whether the required materials are available. This allows you to
-available, and they will be created in a suspended state. Buildingplan will
+focus purely on design elements when you are laying out your fort, and defers
-periodically scan for appropriate items, and the jobs will be unsuspended when
+item production concerns to a more convenient time.
-the items are available.
+
-
+Buildingplan is as an alternative to the vanilla building placement UI. It
-This is very powerful when used with tools like `quickfort`, which allow you to
+appears after you have selected the type of building, furniture, or construction
-set a building plan according to a blueprint, and the buildings will simply be
+that you want to place in the vanilla build menu. Buildingplan then takes over
-built when you can build them.
+for the actual placement step. If any building materials are not available yet
-
+for the placed building, it will be created in a suspended state. Buildingplan
-You can use manager work orders or `workflow` to ensure you always have one or
+will periodically scan for appropriate items and attach them. Once all items are
-two doors/beds/tables/chairs/etc. available, and place as many as you like.
+attached, the construction job will be unsuspended and a dwarf will come and
-Materials are used to build the planned buildings as they are produced, with
+build the building. If you have the `unsuspend` overlay enabled (it is enabled
-minimal space dedicated to stockpiles.
+by default), then buildingplan-suspended buildings will appear with a ``P`` marker
+on the main map, as opposed to the usual ``x`` marker for "regular" suspended
+buildings.
+
+If you want to impose restrictions on which items are chosen for the buildings,
+buildingplan has full support for quality and material filters. Before you place
+a building, you can select a component item in the list and hit ``f`` or click on
+the ``filter`` button next to the item description. This will let you choose your
+desired item quality range, whether the item must be decorated, and even which
+specific materials the item must be made out of. This lets you create layouts
+with a consistent color, if that is part of your design.
+
+If you just care about the heat sensitivity of the building, you can set the
+building to be fire- or magma-proof in the placement UI screen or in any item
+filter screen, and the restriction will apply to all building items. This makes it
+very easy to create magma-safe pump stacks, for example.
+
+Buildingplan works very well in conjuction with other design tools like
+`gui/quickfort`, which allow you to apply a building layout from a blueprint. You
+can apply very large, complicated layouts, and the buildings will simply be built
+when your dwarves get around to producing the needed materials. If you set filters
+in the buildingplan UI before applying the blueprint, the filters will be applied
+to the blueprint buildings, just as if you had planned them from the buildingplan
+placement UI.
+
+One way to integrate buildingplan into your gameplay is to create manager
+workorders to ensure you always have a few blocks/doors/beds/etc. available. You
+can then place as many of each building as you like. Produced items will be used
+to build the planned buildings as they are produced, with minimal space dedicated
+to stockpiles. The DFHack `orders` library can help with setting up these manager
+workorders for you.
+
+If you do not wish to use the ``buildingplan`` interface, you can turn off the
+``buildingplan.planner`` overlay in `gui/overlay`. You should not disable the
+``buildingplan`` service entirely in `gui/control-panel` since then existing
+planned buildings in loaded forts will stop functioning.
 
 Usage
 -----
 
 ::
 
-    enable buildingplan
     buildingplan [status]
-    buildingplan set <setting> true|false
+    buildingplan set <setting> (true|false)
+
+Examples
+--------
+
+``buildingplan``
+    Print a report of current settings, which kinds of buildings are planned,
+    and what kinds of materials the buildings are waiting for.
 
 .. _buildingplan-settings:
 
@@ -49,23 +90,5 @@ want to add this line to your ``dfhack-config/init/onMapLoad.init`` file to
 always configure `buildingplan` to just use blocks for buildings and
 constructions::
 
-    on-new-fortress buildingplan set boulders false; buildingplan set logs false
+    on-new-fortress buildingplan set boulders false
-
+    on-new-fortress buildingplan set logs false
-.. _buildingplan-filters:
-
-Item filtering
---------------
-
-While placing a building, you can set filters for what materials you want the
-building made out of, what quality you want the component items to be, and
-whether you want the items to be decorated.
-
-If a building type takes more than one item to construct, use
-:kbd:`Ctrl`:kbd:`Left` and :kbd:`Ctrl`:kbd:`Right` to select the item that you
-want to set filters for. Any filters that you set will be used for all buildings
-of the selected type placed from that point onward (until you set a new filter
-or clear the current one). Buildings placed before the filters were changed will
-keep the filter values that were set when the building was placed.
-
-For example, you can be sure that all your constructed walls are the same color
-by setting a filter to accept only certain types of stone.