Merge remote-tracking branch 'myk002/quickfort_docs' into develop

data/blueprints/library/dreamfort.csv

@@ -1070,7 +1070,7 @@ query_stockpiles/farming_query_stockpiles
 ,,,,,,,,,,,,,,,,,,,,,bodyparts,linksonly,`,,`,`,`,`,`,`,`,`,`,`,`,`,`,`
 ,,,,,,,,,,,,,,,,,,,,,`,`,`,`,give2left,`,`,`,`,`,`,`,`,`,`,`,`,`
 ,,,,,,,,,,,,,,,,,,,,,`,`,`,,`,`,`,`,`,`,`,`,`,`,`,`,`,`
-,,,,,,,,,,,,,,,,,,,,,,{quantumstopfromnorth}{namelastrouteprefix}Trash Dumper{namelastroutesuffix},,,`,`,`,`,`,`,`,`,`,`,`,`,`,`
+,,,,,,,,,,,,,,,,,,,,,,"{quantumstopfromnorth name=""Trash Dumper""}",,,`,`,`,`,`,`,`,`,`,`,`,`,`,`
 ,,,,,,,,,,,,,,,,,,,,,,quantum,,,`,`,`,`,`,`,`,`,`,`,`,`,`,`
 
 
@@ -1279,7 +1279,7 @@ query/industry_query
 ,,,,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`
 ,,,,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`
 ,,,,`,`,`,`,`,`,`,`,`,`,`,`,`,{quantum}g{Up}{Left 5}&,`,`,`,`,`,`,`,`,`,`,`,`,`
-,,,,`,`,`,`,`,`,`,`,`,`,`,`,`,{quantumstopfromsouth}{namelastrouteprefix}Stoneworker quantum{namelastroutesuffix},`,`,`,`,`,`,`,`,`,`,`,`,`
+,,,,`,`,`,`,`,`,`,`,`,`,`,`,`,"{quantumstopfromsouth name=""Stoneworker quantum""}",`,`,`,`,`,`,`,`,`,`,`,`,`
 ,,,,`,`,`,`,`,`,`,`,`,`,`,`,otherstone,,,`,`,`,`,`,`,`,`,`,`,`,`
 ,,miscliquid,`,`,`,`,`,`,`,`,`,`,`,`,`,~,nocontainers,~,`,`,`,`,`,`,`,`,`,`,`,`,`,steelbars
 ,,nocontainers,`,`,`,`,`,`,`,`,`,`,`,`,`,~,~,~,`,`,`,`,`,`,`,`,`,`,`,`,`,`
@@ -1287,7 +1287,7 @@ query/industry_query
 ,,`,`,`,`,`,`,`,`,`,`,`,`,,,`,,`,,,`,`,`,`,`,`,`,`,`,`,`,`
 ,,`,`,`,`,`,`,`,`,`,`,`,`,,`,`,`,`,`,,`,`,`,`,`,`,`,`,`,`,`,`
 ,,`,`,`,`,`,`,`,`,{cages}{permittraps},,,`,`,`,,,,`,`,`,forbidotherstone,,,`,`,`,`,`,`,`,t{Left 6}{Down}&
-,,`,`,`,`,`,`,{quantum}g{Up 10}{Right 4}&,{quantumstopfromeast}{namelastrouteprefix}Goods/Wood quantum{namelastroutesuffix},~,nocontainers,~,`,,`,,`,,`,,`,~,nocontainers,~,{quantumstopfromwest}{namelastrouteprefix}Metalworker quantum{namelastroutesuffix},quantum,`,`,`,`,`,`
+,,`,`,`,`,`,`,{quantum}g{Up 10}{Right 4}&,"{quantumstopfromeast name=""Goods/Wood quantum""}",~,nocontainers,~,`,,`,,`,,`,,`,~,nocontainers,~,"{quantumstopfromwest name=""Metalworker quantum""}",quantum,`,`,`,`,`,`
 ,,`,`,`,`,`,`,`,`,{tallow}{permitdye},,,`,`,`,,,,`,`,`,forbidpotash,,,`,`,`,`,`,`,`,t{Left 6}{Up}&
 ,,`,`,`,`,`,`,`,`,`,`,`,`,,`,`,`,`,`,,`,`,`,`,`,`,`,`,`,`,`,`
 ,,`,`,`,`,`,`,`,`,`,`,`,`,,,`,,`,,,`,`,`,`,`,`,`,`,`,`,`,`
@@ -1295,7 +1295,7 @@ query/industry_query
 ,,`,`,`,`,`,`,`,`,`,`,`,`,`,`,craftrefuse,,,`,`,`,`,`,`,`,`,`,`,`,`,`,`
 ,,`,`,`,`,`,`,`,`,`,`,`,`,`,`,~,nocontainers,~,`,`,`,`,`,`,`,`,`,`,`,`,`,coal
 ,,,,`,`,`,`,`,`,`,`,`,`,`,`,~,~,~,`,`,`,`,`,nocontainers,`,t{Up 7}&,~,~,~,~
-,,,,`,`,`,`,`,`,`,`,`,`,`,`,`,{quantumstopfromnorth}{namelastrouteprefix}Clothier/Bones quantum{namelastroutesuffix},`,`,`,`,`,`,{ironweapons}{permitsteelweapons}{forbidmasterworkweapons}{forbidartifactweapons}
+,,,,`,`,`,`,`,`,`,`,`,`,`,`,`,"{quantumstopfromnorth name=""Clothier/Bones quantum""}",`,`,`,`,`,`,{ironweapons}{permitsteelweapons}{forbidmasterworkweapons}{forbidartifactweapons}
 ,,,,`,`,`,`,`,`,`,`,`,`,`,`,`,quantum,`,`,`,`,`,`,{ironarmor}{permitsteelarmor},forbidmasterworkarmor,forbidartifactarmor,~,~,~,~
 ,,,,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`
 ,,,,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,nocontainers,give2up,t{Up 11}&,~,~,~,~
@@ -1320,7 +1320,7 @@ Garbage dump
 Manual steps you have to take:
 "If you want to declare the dining room as a tavern, the bedrooms at the top can be assigned to the tavern as rented rooms."
 "Configure the soap stockpiles to take from the industry level ""Metalworker"" quantum stockpile (which holds all the bars)"
-"Convert the bath pit zones to pond zones when you are ready to fill them with 3-depth water. This is the only really fiddly bit, since you have to carefully disable the pond zone again when the final bucket to bring the water to an even 3-depth is on the way."
+"Activate the bath pond zones when you are ready to fill them with 3-depth water. This is the only really fiddly bit, since you have to carefully disable the pond zone again when the final bucket to bring the water to an even 3-depth is on the way."
 "Fill the cisterns with water, either with a bucket brigade or by plumbing flowing water. Fill so that there are two z-levels of 7-depth water. If you want to fill with buckets, designate a pond zone on the level below the main floor. If you feel adventurous and are experienced with water pressure, you can instead route (depressurized!) water to the second-to-bottom level (the one above the up staircases)."
 "#dig label(services1) start(23; 22; staircase center) message(This would be a good time to queue manager orders for /services2. Once the area is dug out, continue with /services2.)"
 
@@ -1533,7 +1533,7 @@ query_stockpiles/services_query_stockpiles
 ,,`,`,`,`,`,`,,`,`,`,`,`,`
 
 
-#zone label(services_zone) start(23; 22) hidden() use the meta blueprints for normal application
+#zone label(services_zone) start(23; 22) hidden() message(activate the bath pond zones when you are ready to fill them with 3-depth water) use the meta blueprints for normal application
 
 
 ,,`,`,`,,,`,`,`,,,`,`,`
@@ -1554,9 +1554,9 @@ query_stockpiles/services_query_stockpiles
 ,,`,`,`,`,`,`,`,`,`,`,`,`,`,,,,`,`,`,`,`,`,`,`,`,,,,`,`,`,`,`,`,`,`,`
 ,,`,`,`,`,`,`,`,`,`,`,`,`,`,,,,,,,,`,,,,,,,,`,`,`,`,`,`,`,`,`
 ,,`,`,`,`,`,`,`,`,`,`,`,`,`,,`,`,`,,`,`,`,`,`,,`,`,`,,`,`,`,`,`,`,`,`,`
-,,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,pa,`,`,`,`,`,`,`,`,`,pa,`,`,`,`,`,`,`,`,`,`,`
+,,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,apPf(1x3),`,`,`,`,`,`,`,`,`,apPf(1x3),`,`,`,`,`,`,`,`,`,`,`
-,,`,`,`,`,`,`,`,`,`,`,`,`,`,,`,pa,`,,`,`,`,`,`,,`,pa,`,,`,`,`,`,`,`,`,`,`
+,,`,`,`,`,`,`,`,`,`,`,`,`,`,,`,~,`,,`,`,`,`,`,,`,~,`,,`,`,`,`,`,`,`,`,`
-,,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,pa,`,`,`,`,`,`,`,`,`,pa,`,`,`,`,`,`,`,`,`,`,`
+,,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,~,`,`,`,`,`,`,`,`,`,~,`,`,`,`,`,`,`,`,`,`,`
 ,,`,`,`,`,`,`,`,`,`,`,`,`,`,,`,`,`,,`,`,`,`,`,,`,`,`,,`,`,`,`,`,`,`,`,`
 ,,`,`,`,`,`,`,`,`,`,`,`,`,`,,,,,,,,d,,,,,,,,`,`,`,`,`,`,`,`,`
 ,,,,,,`,`,,`,`,,,,,,,,,,,,,,,,,,,,`,`,`,`,`,`,`,`,`

data/quickfort/aliases-common.txt

@@ -1,8 +1,8 @@
 # Common baseline for aliases for quickfort query mode blueprints.
 #
-# Please DO NOT EDIT this file directly. Instead, custom aliases should be added
+# Please DO NOT EDIT this file directly. It will get overwritten when DFHack
-# to dfhack-config/quickfort/aliases.txt. See that file for syntax
+# is updated. Instead, custom aliases should be added to
-# documentation.
+# dfhack-config/quickfort/aliases.txt. See that file for syntax documentation.
 #
 # The aliases in this file were tested in DF 0.47.04 on 2020 Jul 18.
 #
@@ -31,14 +31,15 @@ linksonly: a
 nocontainers: CE
 
 # for configuring stockpiles to give to other nearby stockpiles/workshops
-give2up: g{Up 2}&
+give: g{move}&
-give2down: g{Down 2}&
+give2up: {give move={Up 2}}
-give2left: g{Left 2}&
+give2down: {give move={Down 2}}
-give2right: g{Right 2}&
+give2left: {give move={Left 2}}
-give10up: g{Up 10}&
+give2right: {give move={Right 2}}
-give10down: g{Down 10}&
+give10up: {give move={Up 10}}
-give10left: g{Left 10}&
+give10down: {give move={Down 10}}
-give10right: g{Right 10}&
+give10left: {give move={Left 10}}
+give10right: {give move={Right 10}}
 
 # use to toggle a sequence of stockpile options. for example: {togglesequence 5}
 togglesequence: &{Down}
@@ -49,7 +50,7 @@ enablesequence: e{Down}
 # clothes and armor in this quantum stockpile will rot away. If you want bones
 # in your quantum stockpile, apply this alias to a refuse stockpile (but don't
 # put useful clothes or armor in there!)
-quantum: {linksonly}{nocontainers}{enableanimals}{enablefood}{furnitureprefix}{enablestone}{enableammo}{enablecoins}{enablebars}{enablegems}{enablefinishedgoods}{enableleather}{enablecloth}{enablewood}}{enableweapons}{enablearmor}{enablesheet}
+quantum: {linksonly}{nocontainers}{enableanimals}{enablefood}{enablefurniture}{enablestone}{enableammo}{enablecoins}{enablebars}{enablegems}{enablefinishedgoods}{enableleather}{enablecloth}{enablewood}{enableweapons}{enablearmor}{enablesheet}
 
 
 ##################################
@@ -58,25 +59,30 @@ quantum: {linksonly}{nocontainers}{enableanimals}{enablefood}{furnitureprefix}{e
 
 # Run one of the quantumstopfrom* aliases over a track stop that is set to dump
 # into a quantum stockpile. The alias will set up the stop to accept all types
-# (the actual types stored in the quantum stockpile is controlled by the feeder
+# (the actual types stored in the quantum stockpile should be controlled by the
-# stockpile) and link the indicated adjacent feeder stockpile (for example, the
+# feeder stockpile) and link the indicated adjacent feeder stockpile. For
-# quantumstopfromsouth alias will link to a feeder stockpile to the South). All
+# example, the quantumstopfromsouth alias should be used over a track stop set
-# you need to do afterwards is assign a vehicle to the stop (and optionally
+# to dump to the North and take items from a feeder stockpile one tile to the
-# give the route a name --see the namelastroute* aliases below). The track stop
+# South. All you need to do afterwards is assign a vehicle to the stop. The
-# does not need to be constructed yet, but the feeder stockpile needs to exist
+# track stop does not need to be constructed yet, but the feeder stockpile needs
-# so we can link it.
+# to exist so we can link to it.
-quantumstopprefix: ^hrs&xxx&{enablesequence 17}^
+#
-quantumstopfromeast: {quantumstopprefix}s{Right}p^{Left}^q
+# Be sure to define the optional 'name' parameter if you want to give your
-quantumstopfromsouth: {quantumstopprefix}s{Down}p^{Up}^q
+# quantum hauling routes custom names. Keep in mind that names have a maximum
-quantumstopfromwest: {quantumstopprefix}s{Left}p^{Right}^q
+# length of 22 characters. For example:
-quantumstopfromnorth: {quantumstopprefix}s{Up}p^{Down}^q
+#   {quantumstopfromsouth name="Trash Dump"}
-
+#
-# Give a name to the most recently defined route. Keep in mind that names have
+# For several examples of these aliases, see
-# a maximum length of 22 characters. It assumes that the route has exactly one
+# https://docs.google.com/spreadsheets/d/1gvTJxxRxZ5V4vXkqwhL-qlr_lXCNt8176TK14m4kSOU
-# stop defined. Use it with the quantumstopfrom* aliases above like this:
-#   {quantumstopfromeast}{namelastrouteprefix}Trash Dumper{namelastroutesuffix}
 namelastrouteprefix: ^h--n
 namelastroutesuffix: &^q
+namelastroute: {namelastrouteprefix}{name}{namelastroutesuffix}
+quantumstopprefix: ^hrs&xxx&{enablesequence 17}^
+quantumstopsuffix: ^q{namelastroute}
+quantumstopfromeast: {quantumstopprefix}s{Right}p^{Left}{quantumstopsuffix}
+quantumstopfromsouth: {quantumstopprefix}s{Down}p^{Up}{quantumstopsuffix}
+quantumstopfromwest: {quantumstopprefix}s{Left}p^{Right}{quantumstopsuffix}
+quantumstopfromnorth: {quantumstopprefix}s{Up}p^{Down}{quantumstopsuffix}
 
 
 ##################################

dfhack-config/quickfort/aliases.txt

@@ -1,6 +1,6 @@
-# aliases for quickfort query mode blueprints
+# Aliases for quickfort #query mode blueprints
 #
-# This file defines custom keycode shortcuts for query mode blueprints.
+# This file defines custom keycode shortcuts for #query mode blueprints.
 # Definitions in this file take precedence over any definitions in the baseline
 # aliases configuration file at hack/data/quickfort/aliases-common.txt. See that
 # file for the many useful aliases that are already defined.
@@ -69,6 +69,20 @@
 # indicating how many times that alias or keycode should be repeated. For
 # example: "{togglesequence 9}" or "{Down 5}".
 #
+# Finally, you can specify sub-aliases that will only be defined while the
+# current alias is being resolved by adding them after the alias name (but
+# before the repetition number, if it is specified), for example:
+#   {quantumstopfromeast name="Trash Dump"}
+# The value of the sub-alias 'name' is used by quantumstopfromeast (or one of
+# the aliases it calls) to give a useful name to your quantum dump hauling
+# route. You can also use this format to temporarily override the value of an
+# existing regularly-defined alias.
+#
+# Sub-aliases must be in one of the following formats:
+#   subaliasname=valwithnospaces
+#   subaliasname="val with spaces"
+#   subaliasname={someotheralias repetitions}
+#
 # Ctrl, Alt, and Shift modifiers can be specified for the next keycode by adding
 # them into the key sequence. For example, Alt-h is written as "{Alt}h".
 #

docs/guides/quickfort-user-guide.rst

@@ -5,32 +5,38 @@ Quickfort User Guide
 
 `Quickfort <quickfort>` is a DFHack script that helps you build fortresses from
 "blueprint" .csv and .xlsx files. Many applications exist to edit these files,
-such as MS Excel and `Google Sheets <https://sheets.new>`__. You can also build
+such as MS Excel and `Google Sheets <https://sheets.new>`__. Most layout and
-your plan "for real" in Dwarf Fortress, and then export your map using the `blueprint`
+building-oriented DF commands are supported through the use of multiple files or
-plugin. Most layout and building-oriented DF commands are supported through the
+spreadsheets, each describing a different phase of DF construction: designation,
-use of multiple files or spreadsheets, each describing a different phase of DF
+building, placing stockpiles/zones, and setting configuration.
-construction: designation, building, placing stockpiles/zones, and setting
+
-configuration.
+The original idea came from :wiki:`Valdemar's <User:Valdemar>` auto-designation
-
+macro. Joel Thornton reimplemented the core logic in Python and extended its
-The original idea and 1.0 codebase came from :wiki:`Valdemar's <User:Valdemar>`
+functionality with `Quickfort 2.0 <https://github.com/joelpt/quickfort>`__. This
-auto-designation macro. Joel Thornton (joelpt) reimplemented the core logic in
+DFHack-native implementation, called "DFHack Quickfort" or just "quickfort",
-Python and extended its functionality with `Quickfort
+builds upon Quickfort 2.0's formats and features. Any blueprint that worked in
-2.0 <https://github.com/joelpt/quickfort>`__. This DFHack-native implementation,
+Python Quickfort 2.0 should work with DFHack Quickfort. DFHack Quickfort is
-called "DFHack Quickfort" or just "quickfort", builds upon Quickfort 2.0's
+written in Lua and interacts with Dwarf Fortress memory structures directly,
-formats and features. DFHack Quickfort is written in Lua and interacts with
+allowing for instantaneous blueprint application, error checking and recovery,
-Dwarf Fortress memory structures directly, allowing for instantaneous blueprint
+and many other advanced features.
-application, error checking and recovery, and many other advanced features.
 
 This document focuses on DFHack Quickfort's capabilities and teaches players how
-to understand and build blueprint files. Some of the text was originally written
+to understand and create blueprint files. Some of the text was originally
-by Joel Thornton, reused here with his permission.
+written by Joel Thornton, reused here with his permission.
-
+
-For those just looking to apply blueprints, check out the `quickfort command's
+For those just looking to apply existing blueprints, check out the `quickfort
-documentation <quickfort>` for syntax. There are also many ready-to-use blueprints
+command's documentation <quickfort>` for syntax. There are many ready-to-use
-available in the ``blueprints/library`` subfolder in your DFHack installation.
+blueprints available in the ``blueprints/library`` subfolder in your DFHack
-Browse them on your computer or :source:`online <data/blueprints/library>`,
+installation. Browse them on your computer or
-or run ``quickfort list -l`` at the ``[DFHack]#`` prompt to list them, and then
+:source:`online <data/blueprints/library>`, or run ``quickfort list -l`` at the
-``quickfort run`` to apply them to your fort!
+``[DFHack]#`` prompt to list them, and then ``quickfort run`` to apply them to
+your fort!
+
+Before you become an expert at writing blueprints, though, you should know that
+the easiest way to make a quickfort blueprint is to build your plan "for real"
+in Dwarf Fortress and then export your map using the DFHack `blueprint` plugin.
+You can apply those blueprints as-is in your next fort, or you can fine-tune
+them with additional features from this guide.
 
 See the `Links`_ section for more information and online resources.
 
@@ -96,6 +102,7 @@ Features
       created stockpiles
    -  Automatic splitting of stockpiles and zones that exceed maximum dimension
       limits
+   -  Full access to all zone settings, such as hospital supply counts
 
 -  Query mode
 
@@ -478,37 +485,57 @@ It is very common to have stockpiles that accept multiple categories of items or
 zones that permit more than one activity. Although it is perfectly valid to
 declare a single-purpose stockpile or zone and then modify it with a ``#query``
 blueprint, quickfort also supports directly declaring all the types on the
-``#place`` and ``#zone`` blueprints. For example, to declare a 10x10 area that
+``#place`` and ``#zone`` blueprints. For example, to declare a 20x10 stockpile
-is a pasture, a fruit picking area, and a meeting area all at once, you could
+that accepts both corpses and refuse, you could write:
-write:
+
+::
+
+   #place refuse heap
+   yr(20x10)
+
+
+And similarly, to declare a zone that is a pasture, a fruit picking area, and a
+meeting area all at once:
 
 ::
 
    #zone main pasture and picnic area
    nmg(10x10)
 
-And similarly, to declare a stockpile that accepts both corpses and refuse, you
+The order of the individual letters doesn't matter.
-could write:
+
+Detailed configuration for zones, such as the pit/pond toggle, can also be set
+by mimicking the hotkeys used to set them. Note that gather flags default to
+true, so specifying them in a blueprint will turn the toggles off. If you need
+to set configuration from multiple zone subscreens, separate the key sections
+with ``^``. Note the special syntax for setting hospital supply levels, which
+have no in-game hotkeys:
 
 ::
 
-   #place refuse heap
+   #zone a combination hospital and shrub (but not fruit) gathering zone
-   yr(20x10)
+   gGtf^hH{hospital buckets=5 splints=20}(10x10)
 
-The order of the individual letters doesn't matter.
+The valid hospital settings (and their maximum values) are:
+
+::
 
+    thread   (1500000)
+    cloth    (1000000)
+    splints  (100)
+    crutches (100)
+    powder   (15000)
+    buckets  (100)
+    soap     (15000)
+    
 To toggle the ``active`` flag for zones, add an ``a`` character to the string.
-For example, to create a *disabled* pit zone (that you later intend to turn into
+For example, to create a *disabled* pond zone (that you later intend to
-a pond and carefully fill to 3-depth water):
+carefully fill with 3-depth water for a dwarven bathtub):
 
 ::
 
-   #zone disabled future pond zone
+   #zone disabled pond zone
-   pa(1x3)
+   apPf(1x3)
-
-Note that while this notation covers most use cases, tweaking low-level zone
-parameters, like hospital supply levels or converting between pits and ponds,
-must still be done manually or with a ``#query`` blueprint.
 
 Minecart tracks
 ~~~~~~~~~~~~~~~
@@ -1321,11 +1348,6 @@ Hauling routes are notoriously fiddly to set up, but they can be automated with
 blueprints. Check out the Southern area of the ``#place`` and ``#query``
 blueprints for how the quantum garbage dump is configured.
 
-Note that aliases that must be applied in a particular order must appear in the
-same cell. Otherwise there are no guarantees for which cell will be processed
-first. For example, look at the track stop cells in the ``#query`` blueprint for
-how the hauling routes are given names.
-
 The industry_ level: when not to use aliases
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1333,7 +1355,7 @@ The industry_ level: when not to use aliases
 
 The industry level is densely packed and has more complicated examples of
 stockpile configurations and quantum dumps. However, what I'd like to call out
-are the key sequences that are *not* in aliases.
+first are the key sequences that are *not* in aliases.
 
 .. topic:: Tip
 
@@ -1353,6 +1375,45 @@ see in the blueprint itself. Also, if you move the workshop, it's easier to fix
 the stockpile link right there in the blueprint instead of editing the separate
 aliases.txt file.
 
+There are also good examples in the query blueprint for how to use the
+``permit`` and ``forbid`` stockpile aliases.
+
+.. topic:: Tip
+
+     Put all configuration that must be applied in a particular order in the
+     same spreadsheet cell.
+
+Most of the baseline aliases distributed with DFHack fall into one of three
+categories:
+
+# Make a stockpile accept only a particular item type in a category
+# Permit an item type, but do not otherwise change the stockpile configuration
+# Forbid an item type, but do not otherwise change the stockpile configuration
+
+If you have a stockpile that covers multiple tiles, it might seem natural to put
+one alias per spreadsheet cell. The aliases still all get applied to the
+stockpile, and with only one alias per cell, you can just type the alias name
+and avoid having to use the messier-looking ``{alias1}{alias2}`` syntax:
+
+::
+
+    #query Incorrectly configure a 3x3 food stockpile to accept tallow and dye
+    tallow
+    permitdye
+
+However, in quickfort there are no guarantees about which cell will be
+processed first. In the example above, we obviously intend for the food
+stockpile to have everything forbidden, then tallow permitted, then dye
+permitted. The algorithm could happen to apply them in the opposite order,
+though, and we'd end up with dye being permitted, then everything being
+forbidden and tallow being enabled. To make sure you always get what you want,
+write order-sensitive aliases on the same line:
+
+::
+
+    #query Properly configure a 3x3 food stockpile to accept tallow and dye
+    {tallow}{permitdye}
+
 The services_ level: handling multi-level dig blueprints
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~