document (and use) parameterized aliases

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
-# to dfhack-config/quickfort/aliases.txt. See that file for syntax
-# documentation.
+# Please DO NOT EDIT this file directly. It will get overwritten when DFHack
+# is updated. Instead, custom aliases should be added to
+# 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}&
-give2down: g{Down 2}&
-give2left: g{Left 2}&
-give2right: g{Right 2}&
-give10up: g{Up 10}&
-give10down: g{Down 10}&
-give10left: g{Left 10}&
-give10right: g{Right 10}&
+give: g{move}&
+give2up: {give move={Up 2}}
+give2down: {give move={Down 2}}
+give2left: {give move={Left 2}}
+give2right: {give move={Right 2}}
+give10up: {give move={Up 10}}
+give10down: {give move={Down 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}
@@ -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
-# stockpile) and link the indicated adjacent feeder stockpile (for example, the
-# quantumstopfromsouth alias will link to a feeder stockpile to the South). All
-# you need to do afterwards is assign a vehicle to the stop (and optionally
-# give the route a name --see the namelastroute* aliases below). The track stop
-# does not need to be constructed yet, but the feeder stockpile needs to exist
-# so we can link it.
-quantumstopprefix: ^hrs&xxx&{enablesequence 17}^
-quantumstopfromeast: {quantumstopprefix}s{Right}p^{Left}^q
-quantumstopfromsouth: {quantumstopprefix}s{Down}p^{Up}^q
-quantumstopfromwest: {quantumstopprefix}s{Left}p^{Right}^q
-quantumstopfromnorth: {quantumstopprefix}s{Up}p^{Down}^q
-
-# Give a name to the most recently defined route. Keep in mind that names have
-# a maximum length of 22 characters. It assumes that the route has exactly one
-# stop defined. Use it with the quantumstopfrom* aliases above like this:
-#   {quantumstopfromeast}{namelastrouteprefix}Trash Dumper{namelastroutesuffix}
+# (the actual types stored in the quantum stockpile should be controlled by the
+# feeder stockpile) and link the indicated adjacent feeder stockpile. For
+# example, the quantumstopfromsouth alias should be used over a track stop set
+# to dump to the North and take items from a feeder stockpile one tile to the
+# South. All you need to do afterwards is assign a vehicle to the stop. The
+# track stop does not need to be constructed yet, but the feeder stockpile needs
+# to exist so we can link to it.
+#
+# Be sure to define the optional 'name' parameter if you want to give your
+# quantum hauling routes custom names. Keep in mind that names have a maximum
+# length of 22 characters. For example:
+#   {quantumstopfromsouth name="Trash Dump"}
+#
+# For several examples of these aliases, see
+# https://docs.google.com/spreadsheets/d/1gvTJxxRxZ5V4vXkqwhL-qlr_lXCNt8176TK14m4kSOU
 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".
 #