[quickfort] add documentation and test data for config mode (#2070)

- documents the new config mode
- adds integration test data for [quickfort] implement config mode scripts#361
- adds a note recommending that config mode be used instead of the quickfort query_unsafe setting
- converts the dreamfort /setup blueprint to use config mode; also adjust the aliases used in that blueprint to no longer escape from and re-enter query mode
- adds some more distinctive anchor names for the quickfort and blueprint guides

data/blueprints/library/dreamfort.csv

@@ -55,7 +55,7 @@ Optionally copy the premade profession definitions from hack/examples/profession
 Optionally copy the premade Dreamfort embark profile from the online spreadsheets to the data/init/embark_profiles.txt file
 ""
 -- Set settings and preload initial orders --
-quickfort run library/dreamfort.csv -n /setup,# Place the cursor on the center of your starting wagon. Run before making any manual adjustments to settings! Run the /setup_help blueprint for details on what this blueprint does.
+quickfort run library/dreamfort.csv -n /setup,# Run before making any manual adjustments to settings! Run the /setup_help blueprint for details on what this blueprint does.
 "quickfort orders library/dreamfort.csv -n ""/surface2, /farming2, /surface3, /farming3, /industry2, /surface4""","# Queue up orders required to get the fort minimally functional and secure. You can remove the order for the anvil (you brought one with you, right?)."
 ""
 -- Find a good starting spot on the surface --
@@ -134,19 +134,19 @@ The following settings are changed:
 These are all set for your convenience. Nothing in Dreamfort depends on these settings staying as they are. Feel free to change any setting to your personal preference.
 ""
 #aliases
-startnobles: ^n{Down 4}{togglesequence 8}{Up}s{Up}&^^q
-startorders: ^ohrov^Wl^^q
-startburrows: ^wa&nInside&^^q
+startnobles: n{Down 4}{togglesequence 8}{Up}s{Up}&^^
+startorders: ohrov^Wl^^
+startburrows: wa&nInside&^^
 metalarmorsetup: A{Right 2}{Down 2}&{Down}&{Left}&M{Right}{Down}&{Left}{Down}{Right}{Down}&{Left}{Down 2}L{Right}{Down 2}&{Left}{Down 3}&M{Right}{Down}&{Left 2}
-startmilitary: ^mnr{Down}r{metalarmorsetup}{Down}racNSiege&{Right}&^q
+startmilitary: mnr{Down}r{metalarmorsetup}{Down}racNSiege&{Right}&^
 sethotkey: {fkey}n{name}&
-starthotkeys: ^H{sethotkey fkey={F2} name=Farming}{sethotkey fkey={F3} name=Industry}{sethotkey fkey={F4} name=Services}{sethotkey fkey={F5} name=Guildhall}{sethotkey fkey={F6} name=Quarry}{sethotkey fkey={F7} name=Cavern}{sethotkey fkey={F8} name=Magma}^q
+starthotkeys: H{sethotkey fkey={F2} name=Farming}{sethotkey fkey={F3} name=Industry}{sethotkey fkey={F4} name=Services}{sethotkey fkey={F5} name=Guildhall}{sethotkey fkey={F6} name=Quarry}{sethotkey fkey={F7} name=Cavern}{sethotkey fkey={F8} name=Magma}^
 ""
-"#query label(setup) start(center tile of the wagon) message(Please set the zoom targets of the hotkeys (the 'H' menu) according to where you actually end up digging the levels.
+"#config label(setup) message(Please set the zoom targets of the hotkeys (the 'H' menu) according to where you actually end up digging the levels.
 As you build your fort, expand the ""Inside"" burrow to include new civilian-safe areas.
 Optionally, add a leather cloak to your military uniforms to enhance the protection of the uniforms.
 Nothing in Dreamfort depends on these settings staying as they are. Feel free to change any setting to your personal preference.) assign nobles, set standing orders, create burrows, make adjustments to military uniforms, and set hotkey names"
-{startnobles}{startorders}{startburrows}{startmilitary}{starthotkeys}{F1}
+{startnobles}{startorders}{startburrows}{startmilitary}{starthotkeys}
 "#meta label(dig_all) start(central stairs on industry level) dig industry, services, guildhall, suites, and apartments levels. does not include farming."
 # Note that this blueprint will only work for the unified dreamfort.csv. It won't work for the individual .xlsx files (since #meta blueprints can't cross file boundaries).
 ""

data/blueprints/library/test/quickfort/list/all_modes.csv

@@ -3,7 +3,8 @@
 #place hidden()
 #zone hidden()
 #query hidden()
-#meta hidden()
-#notes hidden()
+#config hidden()
 #ignore
 #aliases
+#meta hidden()
+#notes hidden()

dfhack-config/quickfort/quickfort.txt

@@ -22,9 +22,9 @@ force_marker_mode=false
 # Skip query blueprint sanity checks that detect common blueprint errors and
 # halt or skip keycode playback. Checks include ensuring a configurable building
 # exists at the designated cursor position and verifying the active UI screen is
-# the same before and after sending keys for the cursor position. Temporarily
-# enable this if you are running a query blueprint that sends a key sequence
-# that is *not* related to stockpile or building configuration.
+# the same before and after sending keys for the cursor position. If you find
+# you need to enable this for one of your own blueprints, you should probably be
+# using a config blueprint, not a query blueprint.
 query_unsafe=false
 
 # Set to the maximum number of resources you want assigned to stockpiles of the

docs/guides/examples-guide.rst

@@ -1,3 +1,4 @@
+.. _config-examples-guide:
 .. _dfhack-examples-guide:
 
 DFHack Example Configuration File Index

docs/guides/quickfort-library-guide.rst

@@ -1,3 +1,4 @@
+.. _blueprint-library-guide:
 .. _quickfort-library-guide:
 
 Blueprint Library Index

docs/guides/quickfort-user-guide.rst

@@ -1,5 +1,5 @@
-.. _quickfort-user-guide:
 .. _quickfort-blueprint-guide:
+.. _quickfort-user-guide:
 
 Quickfort Blueprint Editing Guide
 =================================
@@ -1077,12 +1077,13 @@ Other blueprint modes
 In addition to the powerful ``#meta`` mode described above, there are a few
 additional blueprint modes that become useful when you are sharing your
 blueprints with others or managing complex blueprint sets. Instead of mapping
-tile positions to map modifications and keystroke sequences like the basic modes
-do, these "blueprints" have specialized, higher-level uses:
+tile positions to map modifications like the basic modes do, these "blueprints"
+have specialized, higher-level uses:
 
 ==============  ===========
 Blueprint mode  Description
 ==============  ===========
+config          Play back key sequences that are not related to map tiles
 notes           Display long messages, such as help text or blueprint
                 walkthroughs
 aliases         Define aliases that can be used by other ``#query`` blueprints
@@ -1091,6 +1092,44 @@ ignore          Hide a section of your spreadsheet from quickfort, useful for
                 scratch space or personal notes
 ==============  ===========
 
+.. _quickfort-config-blueprints:
+
+Config blueprints
+`````````````````
+
+A ``#config`` blueprint is used to send unfiltered keystrokes directly to the
+DF UI without interacting with specific map tiles. They have access to the same
+keystroke aliases as ``#query`` blueprints, but ``#config`` blueprints differ
+from ``#query`` blueprints in a few critical ways:
+
+- Whereas the "home" mode for ``#query`` blueprints is the "query" mode
+  (:kbd:`q`), ``#config`` blueprints start on the default map screen -- the view
+  you have when you're looking at the map with no sidebar visible. The keystroke
+  or alias sequence in each spreadsheet cell in a ``#config`` blueprint must
+  begin and end on the default map screen.
+- The cursor position is not set for ``#config`` blueprints. This means that it
+  doesn't matter what spreadsheet cell you put your text in. The blueprint cell
+  location does not correspond to a map tile.
+
+A ``#config`` blueprint is best used for accessing game menus that are not
+associated with map tiles, such as the hotkey menu (:kbd:`H`), the military
+menu (:kbd:`m`), or the standing orders menu (:kbd:`o`). In other words, use a
+``#config`` blueprint when you want to configure the game itself, not the tiles
+on the map. A ``#config`` blueprint is better for these menus than a ``#query``
+blueprint because the cursor can jump around in unpredictable ways when
+accessing these non-cursor modes and then re-entering query mode. This will
+cause quickfort to detect a ``#query`` blueprint error and stop executing.
+Also, ``#query`` blueprints will skip playing back a key sequence entirely if
+it doesn't detect a building or zone on the target tile. A ``#config``
+blueprint doesn't need a building or zone to exist in order to run.
+
+Note that you *can* enter any mode you want during a ``#config`` blueprint
+keystroke sequence (as long as you get back to the default map screen by the end
+of the sequence), even modes that provide a cursor on the screen. It's just that
+the position of that cursor is not guaranteed to be on any specific tile. If you
+need access to a cursor, you probably should be using a ``#query`` blueprint
+instead.
+
 .. _quickfort-notes:
 
 Notes blueprints
@@ -1779,10 +1818,10 @@ Links
 
 -  `Quickfort command reference <quickfort>`
 -  `quickfort-alias-guide`
--  `quickfort-library-guide`
+-  `blueprint-library-guide`
 -  :forums:`Quickfort forum thread <176889>`
 -  :issue:`DFHack issue tracker <>`
--  :source:`Quickfort blueprint library source <data/blueprints/library>`
+-  :source:`Blueprint library source <data/blueprints/library>`
 -  :source-scripts:`Quickfort source code <internal/quickfort>`
 
 **Related tools:**

scripts

@@ -1 +1 @@
-Subproject commit 946fdffdf113e3ef11aa87b817ee8ea136daad55
+Subproject commit 7205e4ec20d3df0f2c12e2f279cb4d9205673e6c