add pump stack blueprint to the libarary, add docs

data/blueprints/library/pump_stack.csv

@@ -0,0 +1,51 @@
+#notes label(help)
+A pump stack is useful for moving water or magma up through the z-levels.
+""
+To use these blueprints:
+- Measure how many z-levels the pump stack should span.
+"- Position the cursor on the bottom level of the future pump stack. It should be on the z-level just above the liquid you want to pump. Run ""quickfort run library/pump_stack.csv -n /dig2SN"" to see where the suction hole will end up. Replace ""run"" with ""undo"" in the previous command to clean up."
+"- If you need an East-West pump stack, or if you need the staircase in another spot, use the ""--transform"" commandline option to alter the blueprint to your needs. For example: ""quickfort run library/pump_stack.csv -n /dig2SN --transform rotcw,fliph"". If you use a transformation, be sure to use the same option for the remaining commandlines."
+"- Once you have everything lined up, run ""quickfort run library/pump_stack.csv -n /dig2SN --repeat up,20"" to designate the entire pump stack for digging. Replace that last ""20"" with the height of your pump stack divided by 2 (since each repetition of /dig2SN is two z-levels high). If the height ends up being one too many at the top, manually undesignate the top level."
+"- Since you do not need to transmit power down below the lowest level, replace the channel designation on the middle tile of the bottom-most pump stack level with a regular dig designation. Likewise, replace the Up/Down staircase designation on the lowest level with an Up staircase designation."
+"- After the stack is dug out, prepare for building by setting the buildingplan plugin material filters for screw pumps (b-M-s-M). If you are planning to move magma, be sure to select magma-safe materials."
+"- Finally, position the cursor back on the access stairs on the lowest level and run ""quickfort run library/pump_stack.csv -n /build2SN --repeat up,20"" (with 20 replaced with your desired repetition count and with your --transform command, if any)."
+""
+"Sometimes, a screw pump will spontaneously deconstruct while you are building the stack. This will reduce the efficiency of the stack a little, but it's nothing to worry about. Just re-run the /build2SN blueprint over the entire stack to ""fix up"" any broken pieces. The blueprint will harmlessly skip over any correctly-built screw pumps."
+""
+See the wiki for more info on pump stacks: https://dwarffortresswiki.org/index.php/Screw_pump#Pump_stack
+#dig label(digSN) start(2;4;on access stairs) hidden() for a pump from south level
+
+,,,d
+,,,h
+,i,d,d
+,,,h
+
+#dig label(digNS) start(2;4;on access stairs) hidden() for a pump from north level
+
+,,,h
+,d,d,d
+,i,,h
+,,,d
+
+#meta label(dig2SN) start(at the bottom level on the access stairs) 2 levels of pump stack - bottom level pumps from the south
+/digSN
+#<
+/digNS
+#build label(buildSN) start(2;4;on access stairs) hidden() for a pump from south level
+
+,,,`
+,,,~
+,`,`,Msm
+,,,`
+
+#build label(buildNS) start(2;4;on access stairs) hidden() for a pump from north level
+
+,,,`
+,`,`,~
+,`,,Msu
+,,,`
+
+#meta label(build2SN) start(at the bottom level on the access stairs) 2 levels of pump stack - bottom level pumps from the south
+/buildSN
+#<
+/buildNS

docs/guides/quickfort-library-guide.rst

@@ -9,7 +9,7 @@ library blueprints by running ``quickfort list --library`` or by hitting
 :kbd:`Alt`:kbd:`l` in the ``quickfort gui`` interactive dialog.
 
 Each file is hyperlinked to its online version so you can see exactly what the
-blueprints do.
+blueprints do before you run them.
 
 Whole fort blueprint sets
 -------------------------
@@ -128,8 +128,8 @@ The Quick Fortress
 ~~~~~~~~~~~~~~~~~~
 
 The Quick Fortress is an updated version of the example fortress that came with
-`Python Quickfort 2.0 <https://github.com/joelpt/quickfort>`__ (the program
-DFHack quickfort was inspired by). While it is not a complete fortress by
+`Python Quickfort 2.0 <https://github.com/joelpt/quickfort>`__ (the utility that
+inspired DFHack quickfort). While it is not a complete fortress by
 itself, it is much simpler than Dreamfort and is good for a first introduction
 to `quickfort` blueprints. Read its walkthrough with ``quickfort run
 library/quickfortress.csv``.
@@ -174,7 +174,8 @@ Exploratory mining
 ------------------
 
 Several mining patterns to choose from when searching for gems or ores. The
-patterns can be repeated up or down z-levels for exploring through the depths.
+patterns can be repeated up or down z-levels (via quickfort's ``--repeat``
+commandline option) for exploring through the depths.
 
 - :source:`library/exploratory-mining/tunnels.csv <data/blueprints/library/exploratory-mining/tunnels.csv>`
 - :source:`library/exploratory-mining/vertical-mineshafts.csv <data/blueprints/library/exploratory-mining/vertical-mineshafts.csv>`
@@ -186,8 +187,13 @@ Miscellaneous
 Extra blueprints that are useful in specific situations.
 
 - :source:`library/embark.csv <data/blueprints/library/embark.csv>`
+- :source:`library/pump_stack.csv <data/blueprints/library/pump_stack.csv>`
 
 The embark blueprints are useful directly after embark. It contains a ``#build``
 blueprint that builds important starting workshops (mason, carpenter, mechanic,
 and craftsdwarf) and a ``#place`` blueprint that lays down a pattern of useful
 starting stockpiles.
+
+The pump stack blueprints help you move water and magma up to move convenient
+locations in your fort. See the step-by-step guide for using it by running
+``quickfort run library/pump_stack.csv -n /help``.