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

data/quickfort/aliases-common.txt

@@ -17,10 +17,6 @@
 #
 # Aliases that don't fit into those two categories have comments explaining
 # their usage.
-#
-# There is also a non-alphanumeric alias built into the code for the common
-# shorthand for "make room":
-#   r+   expands to r+&
 
 
 ########################################
@@ -41,6 +37,10 @@ give10down: {give move={Down 10}}
 give10left: {give move={Left 10}}
 give10right: {give move={Right 10}}
 
+# Keep in mind that building, stockpile, and zone names have a maximum length
+# of 20 characters. usage example: {givename name="myname"}
+givename: {Ctrl}n{name}&
+
 # use to toggle a sequence of stockpile options. for example: {togglesequence 5}
 togglesequence: &{Down}
 togglesequence2: &{Down 2}
@@ -50,7 +50,9 @@ 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}{enablefurniture}{enablestone}{enableammo}{enablecoins}{enablebars}{enablegems}{enablefinishedgoods}{enableleather}{enablecloth}{enablewood}{enableweapons}{enablearmor}{enablesheet}
+# Optionally set a name for the stockpile by specifying the 'name' parameter,
+# for example: {quantum name="my name"}
+quantum: {linksonly}{nocontainers}{enableanimals}{enablefood}{enablefurniture}{enablestone}{enableammo}{enablecoins}{enablebars}{enablegems}{enablefinishedgoods}{enableleather}{enablecloth}{enablewood}{enableweapons}{enablearmor}{enablesheet}{givename}
 
 
 ##################################
@@ -85,6 +87,14 @@ quantumstopfromwest: {quantumstopprefix}s{Left}p^{Right}{quantumstopsuffix}
 quantumstopfromnorth: {quantumstopprefix}s{Up}p^{Down}{quantumstopsuffix}
 
 
+##################################
+# zone aliases
+##################################
+
+# usage example: {namezone name="my zone name"}
+namezone: ^i{givename}^q
+
+
 ##################################
 # animal stockpile adjustments
 ##################################

dfhack-config/quickfort/aliases.txt

@@ -58,12 +58,12 @@
 # The syntax for defining aliases is:
 #   aliasname: keystrokes
 #
-# Where aliasname is at least two letters or digits long and keystrokes are
+# Where aliasname is at least two letters or digits long (including dashes and
-# whatever you would type into the DF UI. A keystroke can also be a named
+# underscores) and keystrokes are whatever you would type into the DF UI. A
-# keycode from the DF interface definition file (data/init/interface.txt),
+# keystroke can also be a named keycode from the DF interface definition file
-# enclosed in curly brackets like an alias, like: "{Right}" or "{Enter}". In
+# (data/init/interface.txt), enclosed in curly brackets like an alias, like:
-# order to avoid naming conflicts between aliases and keycodes, the convention
+# "{Right}" or "{Enter}". In # order to avoid naming conflicts between aliases
-# is to start aliases with a lowercase letter.
+# and keycodes, the convention is to start aliases with a lowercase letter.
 #
 # Anything enclosed within curly brackets can also have a number after it,
 # indicating how many times that alias or keycode should be repeated. For
@@ -95,8 +95,12 @@
 #   !   expands to {Ctrl}
 #   ^   expands to {ESC}
 #
+# There is also a non-standard alias built into the code for the common
+# shorthand for "make room":
+#   r+  expands to r+&
+#
 # If you need literal verisons of the shorthand characters, surround them in
-# curly brackets, for example: "{~}"
+# curly brackets, for example: "{!}"
 #
 #
 # Add your custom aliases here:

docs/guides/quickfort-user-guide.rst

@@ -502,7 +502,11 @@ meeting area all at once:
    #zone main pasture and picnic area
    nmg(10x10)
 
-The order of the individual letters doesn't matter.
+The order of the individual letters doesn't matter. If you want to configure the
+stockpile from scratch in a ``#query`` blueprint, you can place unconfigured
+"custom" stockpiles with (:kbd:`c`). It is more efficient, though, to place
+stockpiles using the keys that represent the types you want to store, and
+then only use a ``#query`` blueprint if you need fine-grained customization.
 
 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
@@ -892,13 +896,13 @@ Meta blueprints
 Meta blueprints are blueprints that script a series of other blueprints. Many
 blueprint packages follow this pattern:
 
--  Apply dig blueprint to designate dig areas
+1.  Apply dig blueprint to designate dig areas
--  Wait for miners to dig
+#.  Wait for miners to dig
--  **Apply build buildprint** to designate buildings
+#.  **Apply build buildprint** to designate buildings
--  **Apply place buildprint** to designate stockpiles
+#.  **Apply place buildprint** to designate stockpiles
--  **Apply query blueprint** to configure stockpiles
+#.  **Apply query blueprint** to configure stockpiles
--  Wait for buildings to get built
+#.  Wait for buildings to get built
--  Apply a different query blueprint to configure rooms
+#.  Apply a different query blueprint to configure rooms
 
 Those three "apply"s in the middle might as well get done in one command instead
 of three. A meta blueprint can encode that sequence. A meta blueprint refers to
@@ -942,12 +946,12 @@ blueprints into one:
 
 Now your sequence is shortened to:
 
--  Apply dig blueprint to designate dig areas
+1.  Apply dig blueprint to designate dig areas
--  Wait for miners to dig
+#.  Wait for miners to dig
--  **Apply meta buildprint** to build buildings and designate/configure
+#.  **Apply meta buildprint** to build buildings and designate/configure
-   stockpiles
+    stockpiles
--  Wait for buildings to get built
+#.  Wait for buildings to get built
--  Apply the final query blueprint to configure the room
+#.  Apply the final query blueprint to configure the room
 
 You can use meta blueprints to lay out your fortress at a larger scale as well.
 The ``#<`` and ``#>`` notation is valid in meta blueprints, so you can, for
@@ -1010,6 +1014,11 @@ a big fort, so we're planning for a lot of bedrooms):
 Note that for blueprints without an explicit label, we still need to address
 them by their auto-generated numerical label.
 
+It's worth calling out that ``#meta`` blueprints can only refer to blueprints
+that are defined in the same file. This means that all blueprints that a
+``#meta`` blueprint needs to script must be in sheets within the same
+.xlsx spreadsheet or concatenated into the same .csv file.
+
 You can then hide the blueprints that you now manage with the ``#meta``-mode
 blueprint from ``quickfort list`` by adding a ``hidden()`` marker to their
 modelines. That way the output of ``quickfort list`` won't be cluttered by